Users

Set User Permissions

Changed on

Set the assigned permissions for a user.

put/users/{user_id}/permissions

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /users/{user_id}/permissions
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL /authorize, token URL /oauth/token)

Path parameters

user_idstring required

ID of the user.

Example:usr_6968b3987ee4c3ec0b4ee3b9

Request body

permissionsstring[] required

Permissions to assign to the user; replaces the current assigned set.

Example request

{
  "permissions": [
    "users:write",
    "agents:read"
  ]
}

Response

Successful Response

activeboolean required

Whether the user account is enabled.

auth_providerstring required

How the user authenticates: local (password) or external.

created_atstring date-time required

When the user was created (RFC 3339).

emailstring required

Email address of the user.

external_subject_idstring nullable

Subject ID from the external identity provider; null for local users.

first_namestring required

First name of the user.

idstring required

Unique ID of the user.

invite_statestring required

Invitation state: pending, redeemed, accepted or expired. expired means a pending invite whose token has lapsed and should be reissued.

last_namestring required

Last name of the user.

must_change_passwordboolean required

Whether the user must change their password at next use.

namestring required

Full display name: first name and last name.

updated_atstring date-time nullable

When the user was last updated (RFC 3339); null if never updated.

Example response

{
  "active": true,
  "auth_provider": "external",
  "created_at": "2026-01-15T09:30:00Z",
  "email": "ada@example.com",
  "external_subject_id": "auth0|6568b3984d1c238dbe7e2e29",
  "first_name": "Ada",
  "id": "usr_6968b3987ee4c3ec0b4ee3b9",
  "invite_state": "accepted",
  "last_name": "Lovelace",
  "must_change_password": false,
  "name": "Ada Lovelace",
  "permissions": {
    "assigned": [
      "users:write",
      "agents:read"
    ],
    "effective": [
      {
        "implied_by": "users:write",
        "name": "users:read"
      }
    ]
  },
  "updated_at": "2026-01-20T14:05:00Z"
}

Changes