Skip to main content

Endpoint

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:
Required scope: users:write
The new user is recorded as created by the access token’s user.

Request Body

The request body must be a JSON object with the following fields:

Required Fields

Optional Fields

Request Example

Response

Success Response

Status Code: 200 OK

Response Fields

Error Responses

400 Bad Request

Returned when the request is invalid - for example, a malformed email or a user that already exists - or when the access token has no user behind it. client_credentials tokens act as the admin who created the application, so this applies only to tokens issued before application creators were recorded.

401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an X-API-Key was sent instead of a bearer token. See OAuth error responses.

403 Forbidden

Returned when the token does not carry the required scope.

422 Unprocessable Entity

Returned when the request body fails validation.

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

500 Internal Server Error

Returned when the user could not be created due to a server error.

Notes

The new user is always created in the organization the token is bound to. The role defaults to viewer if omitted - set role explicitly to grant broader access.
users:write allows creating users with any role, including admin. Grant this scope only to applications that genuinely need to provision users.

Use Cases

This endpoint is useful for:
  • User provisioning - Programmatically onboard users from an external system
  • SSO onboarding - Pre-create SSO users so they can sign in via your identity provider
  • Auditable provisioning - Record which administrator’s session created each user