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.

📘
Learn more about entities, entity users, and the Monite account structure.

Create a user role

Every entity user should have a corresponding role, which defines a set of permissions to perform certain actions in the system.

The role is 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 the read permission for comment and payable objects:

curl -X POST 'https://api.sandbox.monite.com/v1/roles' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
      "name": "View payables",
      "permissions": {
        "objects": [
          {
            "object_type": "comment",
            "actions": [
              {
                "action_name": "read",
                "permission": "allowed"
              }
            ]
          },
          {
            "object_type": "payable",
            "actions": [
              {
                "action_name": "read",
                "permission": "allowed"
              }
            ]
          }
        ] 
      }
    }'

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

{
  "id": "2724e6bf-17b8-4462-b2ed-7d3e16c4a133",
  "name": "View payables",
  "permissions": {
    "objects": [
      {
        "object_type": "comment",
        "actions": [
          {
            "action_name": "read",
            "permission": "allowed"
          }
        ]
      },
      {
        "object_type": "payable",
        "actions": [
          {
            "action_name": "read",
            "permission": "allowed"
          }
        ]
      }
    ]
  },
  "status": "active",
  "created_at": "2022-09-28T12:06:01.589258+00:00",
  "updated_at": "2022-09-28T12:06:01.589272+00:00"
}

The information about the 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:

curl -X POST 'https://api.sandbox.monite.com/v1/entity_users' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "login": "Gardner.Waelchi",
       "first_name": "Gardner",
       "last_name": "Waelchi",
       "role_id": "946141f3-ca01-44dc-b1a6-1024aa71f978",
       "email": "[email protected]",
       "phone": "+15551234567",
       "title": "Mr."
     }'

The successful response contains the created entity user:

{
  "id": "e4e422fc-6956-4fdd-b091-920329f8b92e",
  "role_id": "946141f3-ca01-44dc-b1a6-1024aa71f978",
  "userpic": null,
  "login": "Gardner.Waelchi",
  "first_name": "Gardner",
  "last_name": "Waelchi",
  "status": "active",
  "created_at": "2022-04-21T14:39:39.554700+00:00",
  "updated_at": "2022-04-21T14:39:39.554710+00:00",
  "email": "[email protected]",
  "phone": "+15551234567",
  "userpic_file_id": null
}

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}.

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:

{
  "grant_type": "entity_user",
  "client_id": "YOUR_PARTNER_API_KEY",
  "client_secret": "YOUR_PARTNER_API_SECRET",
  "entity_user_id": "USER_ID"
}

For example:

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

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

{
  "access_token": "L8qq9PZyRg6ie...",
  "token_type": "Bearer",
  "expires_in": 86400
}

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:

curl -X GET 'https://api.sandbox.monite.com/v1/entity_users/me' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -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:

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

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:

curl -X PATCH 'https://api.sandbox.monite.com/v1/entity_users/me' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ENTITY_USER_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "last_name" : "Scott"
     }'

The successful response returns the information about the authenticated entity user including the updated data.

Get the roles of the authenticated entity user

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

curl -X GET 'https://api.sandbox.monite.com/v1/entity_users/my_role' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ENTITY_USER_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \

The successful response returns the information about the roles of the authenticated entity user.