Entity users

Overview

Once the customers are mapped out as entities, the next step is to start mapping out their employees to the corresponding entity users in the Monite platform.

Create a user role

Every entity user must have a role. A role defines the permissions that a user has to access and update the entity’s resources in Monite.

Roles are created by calling POST /roles. The partner-level token and the entity ID are required for this action.

In the example below, a new role is created to allow read access to the comment and payable objects:

1
curl -X POST 'https://api.sandbox.monite.com/v1/roles' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
      "name": "View payables",
8
      "permissions": {
9
        "objects": [
10
          {
11
            "object_type": "comment",
12
            "actions": [
13
              {
14
                "action_name": "read",
15
                "permission": "allowed"
16
              }
17
            ]
18
          },
19
          {
20
            "object_type": "payable",
21
            "actions": [
22
              {
23
                "action_name": "read",
24
                "permission": "allowed"
25
              }
26
            ]
27
          }
28
        ]
29
      }
30
    }'

The successful response contains the information about the role, including the role ID that you will require later.

1
{
2
  "id": "2724e6bf-17b8-4462-b2ed-7d3e16c4a133",
3
  "name": "View payables",
4
  "permissions": {
5
    "objects": [
6
      {
7
        "object_type": "comment",
8
        "actions": [
9
          {
10
            "action_name": "read",
11
            "permission": "allowed"
12
          }
13
        ]
14
      },
15
      {
16
        "object_type": "payable",
17
        "actions": [
18
          {
19
            "action_name": "read",
20
            "permission": "allowed"
21
          }
22
        ]
23
      }
24
    ]
25
  },
26
  "status": "active",
27
  "created_at": "2022-09-28T12:06:01.589258+00:00",
28
  "updated_at": "2022-09-28T12:06:01.589272+00:00"
29
}

For the full list of permissions, see List of permissions. The information about the created role can be retrieved later by calling GET /roles/{role_id}.

Create an entity user

To create an entity user, call POST /entity_users. Specify the entity ID in the X-Monite-Entity-Id request header and the user data in the request body. The role_id field must be populated by the ID of the role created earlier. The request must be authorized using a partner-level access token:

1
curl -X POST 'https://api.sandbox.monite.com/v1/entity_users' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "login": "Gardner.Waelchi",
8
       "first_name": "Gardner",
9
       "last_name": "Waelchi",
10
       "role_id": "946141f3-ca01-44dc-b1a6-1024aa71f978",
11
       "email": "g.waelchi@example.com",
12
       "phone": "+15551234567",
13
       "title": "Mr."
14
     }'

The successful response contains the created entity user:

1
{
2
  "id": "e4e422fc-6956-4fdd-b091-920329f8b92e",
3
  "role_id": "946141f3-ca01-44dc-b1a6-1024aa71f978",
4
  "userpic": null,
5
  "login": "Gardner.Waelchi",
6
  "first_name": "Gardner",
7
  "last_name": "Waelchi",
8
  "status": "active",
9
  "created_at": "2022-04-21T14:39:39.554700+00:00",
10
  "updated_at": "2022-04-21T14:39:39.554710+00:00",
11
  "email": "g.waelchi@example.com",
12
  "phone": "+15551234567",
13
  "userpic_file_id": null
14
}

List all entity users

To get information about all the entity users managed by the entity, call GET /entity_users.

Retrieve an entity user

To get information about a specific entity user, call GET /entity_users/{entity_user_id}.

Edit an entity user

To edit an existing entity user, call PATCH /entity_users/{entity_user_id}.

Delete an entity user

To delete an existing entity user, call DELETE /entity_users/{entity_user_id}.

Get an entity user token

To make API calls on behalf of an entity user, you need to use an access token of that user. To get this token, call POST /auth/token with the following request body:

1
{
2
  "grant_type": "entity_user",
3
  "client_id": "YOUR_PARTNER_API_KEY",
4
  "client_secret": "YOUR_PARTNER_API_SECRET",
5
  "entity_user_id": "USER_ID"
6
}

For example:

1
curl -X POST 'https://api.sandbox.monite.com/v1/auth/token' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'Content-Type: application/json' \
4
     -d '{
5
       "grant_type": "entity_user",
6
       "client_id": "2e0c68d6-00b7-447d-b26c-415bbcbfc026",
7
       "client_secret": "cf0de0bd-a59e-473f-a3dd-db5924bd8622",
8
       "entity_user_id": "0c76febf-aabb-451a-aabb-ea3b47689dc1"
9
     }'

The successful response contains the access token for the specified user:

1
{
2
  "access_token": "L8qq9PZyRg6ie...",
3
  "token_type": "Bearer",
4
  "expires_in": 86400
5
}

This token can be sent in the Authorization: Bearer TOKEN request header as an alternative to using a partner-level token.

Get and update the authenticated user info

The authenticated entity user can check all its own information by calling GET /entity_users/me. The request must be authorized using an entity user level-access token:

1
curl -X GET 'https://api.sandbox.monite.com/v1/entity_users/me' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ENTITY_USER_ACCESS_TOKEN'

The successful response returns the information about the authenticated entity user, including the user ID, role, and other details:

1
{
2
  "id": "24c9b573-7e61-4083-9115-b162cc4b9421",
3
  "role_id": "84f48b5c-c24f-48f8-9c33-411a990512c9",
4
  "login": "Hadley80",
5
  "first_name": "Amie",
6
  "last_name": "Thiel",
7
  "status": "active",
8
  "created_at": "2022-09-21T14:59:00.780705+00:00",
9
  "updated_at": "2022-09-21T14:59:00.780715+00:00",
10
  "userpic_file_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
11
}

The authenticated entity user can also make changes to its own information by calling PATCH /entity_users/me, passing the information they wish to update. In the example below, the last_name field is being updated. The request must be authorized using an entity user level-access token:

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/entity_users/me' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ENTITY_USER_ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "last_name" : "Scott"
8
     }'

The successful response returns the updated user object.

Get the role of the authenticated entity user

To retrieve information about the role and permissions assigned to the authenticated entity user, call GET /entity_users/my_role:

1
curl -X GET 'https://api.sandbox.monite.com/v1/entity_users/my_role' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ENTITY_USER_ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \

The successful response returns the role object associated with the authenticated entity user.