Endpoint
Authentication
This endpoint requires an OAuth access token. Send it as a bearer token: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 anX-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.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