> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.monite.com/v2024-01-31/entities/users/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server. # Entity users ## Overview Once the customers are [mapped out as entities](./index), the next step is to start mapping out their employees to the corresponding entity users in the Monite platform. > **Note** > > Learn more about [entities, entity users, and the Monite account structure](../intro/account-structure). ## Create a user role \[#create-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](../get-started/credentials#generate-partner-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: ```sh 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. ```json { "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" } ``` For the full list of permissions, see [List of permissions](/v2024-01-31/api/concepts/authentication#permissions). The information about the created role can be retrieved later by calling [`GET /roles/{role_id}`](/v2024-01-31/api/roles/get-roles-id). ## Create an entity user \[#create] 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](../get-started/credentials#generate-partner-token): ```sh 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": "g.waelchi@example.com", "phone": "+15551234567", "title": "Mr." }' ``` The successful response contains the created entity user: ```json { "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": "g.waelchi@example.com", "phone": "+15551234567", "userpic_file_id": null } ``` ## List all entity users \[#list-a;;] To get information about all the entity users managed by the entity, call [`GET /entity_users`](/v2024-01-31/api/entity-users/get-entity-users). ## Retrieve an entity user \[#retrieve] To get information about a specific entity user, call [`GET /entity_users/{entity_user_id}`](/v2024-01-31/api/entity-users/get-entity-users-id). ## Edit an entity user \[#edit] To edit an existing entity user, call [`PATCH /entity_users/{entity_user_id}`](/v2024-01-31/api/entity-users/patch-entity-users-id). ## Delete an entity user To delete an existing entity user, call [`DELETE /entity_users/{entity_user_id}`](/v2024-01-31/api/entity-users/delete-entity-users-id). ## Get an entity user token \[#get-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`](/v2024-01-31/api/access-tokens/post-auth-token) with the following request body: ```json { "grant_type": "entity_user", "client_id": "YOUR_PARTNER_API_KEY", "client_secret": "YOUR_PARTNER_API_SECRET", "entity_user_id": "USER_ID" } ``` For example: ```sh 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: ```json { "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 \[#current-user] The authenticated entity user can check all its own information by calling [`GET /entity_users/me`](/v2024-01-31/api/entity-users/get-entity-users-me). The request must be authorized using an [entity user level-access token](#get-entity-user-token): ```sh 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: ```json { "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`](/v2024-01-31/api/entity-users/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](#get-entity-user-token): ```sh 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 updated user object. ## Get the role of the authenticated entity user \[#get-current-user-role] To retrieve information about the role and permissions assigned to the authenticated entity user, call [`GET /entity_users/my_role`](/v2024-01-31/api/entity-users/get-entity-users-my-role): ```sh 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 role object associated with the authenticated entity user. > Learn how to manage your customers' employees.