Users

Create User

Changed on

Create a new user and issue an invite token.

post/users

Request

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

Request body

emailstring required

Email address of the new user; must be unique.

first_namestring required

First name of the new user.

last_namestring required

Last name of the new user.

permissionsstring[]

Permissions to assign to the new user; the caller may only grant permissions they hold. Defaults to none.

Example request

{
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "permissions": [
    "users:read",
    "agents:read"
  ]
}

Response

Successful Response

invite_expires_atstring date-time required

When the invite token expires (RFC 3339).

invite_tokenstring required

One-time invite token the user redeems to set a password.

Example response

{
  "invite_expires_at": "2026-01-22T09:30:00Z",
  "invite_token": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "user": {
    "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