> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.monite.com/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-05-25' \
     -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](/api/concepts/authentication#permissions). The information about the created role can be retrieved later by calling [`GET /roles/{role_id}`](/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-05-25' \
     -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`](/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}`](/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}`](/api/entity-users/patch-entity-users-id).

## Delete an entity user

To delete an existing entity user, call [`DELETE /entity_users/{entity_user_id}`](/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`](/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-05-25' \
     -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`](/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-05-25' \
     -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`](/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-05-25' \
     -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`](/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-05-25' \
     -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.