v1.
4
User Management API
[Link]
Manage users, roles, and permissions within your organization. Supports SCIM 2.0 provisioning so identity
providers such as Okta and Azure AD can keep user records in sync. Default rate limit: 500 requests per
minute.
On This Page
●
Authentication
●
Pagination
●
Endpoints overview
●
List, create, update, and delete users
●
Manage roles assigned to a user
●
Roles & Permissions reference
●
SCIM Provisioning
●
Rate Limits & Quotas
●
Error Codes
●
Versioning & Changelog
●
SDKs & Client Libraries
Authentication
All requests must include an Authorization: Bearer <token> header. Tokens are issued per
organization from the admin dashboard under Settings → API Tokens and can be scoped to
read-only or read-write access.
Authorization: Bearer org_live_8pK3...mZ7q
Pagination
List endpoints use page-based pagination via the page and per_page query parameters. The response
meta object reports the total number of matching records so clients can compute the total page count.
{
"total": 142,
"page": 1,
"per_page": 20
}
Endpoints
GET /users
List all users in the organization
POST /users
Create a new user
GET /users/{user_id}
Get a single user by ID
PUT /users/{user_id}
Replace a user record entirely
PATCH /users/{user_id}
Partially update a user
DELETE /users/{user_id}
Deactivate or permanently delete a user
GET /users/{user_id}/roles
List roles assigned to a user
POST /users/{user_id}/roles
Assign a role to a user
GET /users — List Users
Returns a paginated list of user objects, ordered by creation date.
Query Parameters
Parameter Type Required Description
page integer No Page number, starting at 1 (default: 1)
per_page integer No Results per page, max 100 (default: 20)
status string No Filter by status: active, inactive, pending
role string No Filter by role slug, e.g. admin, viewer
q string No Full-text search across name and email
Code Samples
cURL
curl -X GET \
"[Link] \
-H "Authorization: Bearer $API_KEY"
Python
import requests
url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = [Link](url, headers=headers)
print([Link]())
[Link]
const res = await fetch("[Link] {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await [Link]();
Response Fields
Field Type Description
id string Unique identifier for the user
email string Email address
name string Full display name
status string active, inactive, or pending
roles array Role slugs assigned to the user
created_at string ISO 8601 timestamp of when the user was created
Example Response
{
"data": [
{
"id": "usr_7Hk2mP9qR",
"email": "alice@[Link]",
"name": "Alice Müller",
"status": "active",
"roles": [
"admin"
],
"created_at": "2025-03-15T09:41:00Z"
}
],
"meta": {
"total": 1,
"page": 1,
"per_page": 20
}
}
POST /users — Create User
Creates a new user and, unless send_invite is false, sends an invitation email containing a link to set a
password.
Request Body
Parameter Type Required Description
email string Yes Unique email address for the new user
name string Yes Full display name
role string No Initial role slug (default: viewer)
send_invite boolean No Send invitation email (default: true)
Example Request
POST /users
{
"email": "alice@[Link]",
"name": "Alice Müller",
"role": "admin",
"send_invite": true
}
Code Samples
cURL
curl -X POST \
"[Link] \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "alice@[Link]",
"name": "Alice Müller",
"role": "admin",
"send_invite": true
}'
Python
import requests
url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
payload = {
"email": "alice@[Link]",
"name": "Alice Müller",
"role": "admin",
"send_invite": true
}
resp = [Link](url, headers=headers, json=payload)
print([Link]())
[Link]
const res = await fetch("[Link] {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: [Link]({"email": "alice@[Link]", "name": "Alice Müller",
"role": "admin", "send_invite": true}),
});
const data = await [Link]();
Response Fields
Field Type Description
id string Unique identifier for the user
email string Email address
name string Full display name
status string active, inactive, or pending
roles array Role slugs assigned to the user
created_at string ISO 8601 timestamp of when the user was created
Example Response
{
"id": "usr_7Hk2mP9qR",
"email": "alice@[Link]",
"name": "Alice Müller",
"status": "pending",
"roles": [
"admin"
],
"created_at": "2025-03-15T09:41:00Z"
}
GET /users/{user_id} — Get User
Retrieves the details of a single user by ID.
Path Parameters
Field Type Description
user_id string Unique identifier of the user
Code Samples
cURL
curl -X GET \
"[Link] \
-H "Authorization: Bearer $API_KEY"
Python
import requests
url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = [Link](url, headers=headers)
print([Link]())
[Link]
const res = await fetch("[Link] {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await [Link]();
Response Fields
Field Type Description
id string Unique identifier for the user
email string Email address
name string Full display name
status string active, inactive, or pending
roles array Role slugs assigned to the user
created_at string ISO 8601 timestamp of when the user was created
Example Response
{
"id": "usr_7Hk2mP9qR",
"email": "alice@[Link]",
"name": "Alice Müller",
"status": "active",
"roles": [
"admin"
],
"created_at": "2025-03-15T09:41:00Z"
}
PUT /users/{user_id} — Replace User
Replaces the entire user record. Fields omitted from the request body are reset to their default values, so
this endpoint is typically used for full profile updates.
Path Parameters
Field Type Description
user_id string Unique identifier of the user
Request Body
Parameter Type Required Description
email string Yes Email address
name string Yes Full display name
role string Yes Role slug, e.g. admin, editor, viewer
status string Yes active, inactive, or pending
Example Request
PUT /users/{user_id}
{
"email": "alice@[Link]",
"name": "Alice Müller",
"role": "admin",
"status": "active"
}
Code Samples
cURL
curl -X PUT \
"[Link] \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "alice@[Link]",
"name": "Alice Müller",
"role": "admin",
"status": "active"
}'
Python
import requests
url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
payload = {
"email": "alice@[Link]",
"name": "Alice Müller",
"role": "admin",
"status": "active"
}
resp = [Link](url, headers=headers, json=payload)
print([Link]())
[Link]
const res = await fetch("[Link] {
method: "PUT",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: [Link]({"email": "alice@[Link]", "name": "Alice Müller",
"role": "admin", "status": "active"}),
});
const data = await [Link]();
Response Fields
Field Type Description
id string Unique identifier for the user
email string Email address
name string Full display name
status string active, inactive, or pending
roles array Role slugs assigned to the user
created_at string ISO 8601 timestamp of when the user was created
Example Response
{
"id": "usr_7Hk2mP9qR",
"email": "alice@[Link]",
"name": "Alice Müller",
"status": "active",
"roles": [
"admin"
],
"created_at": "2025-03-15T09:41:00Z"
}
PATCH /users/{user_id} — Partially Update User
Updates one or more fields on a user record. Fields not present in the request body are left unchanged.
Path Parameters
Field Type Description
user_id string Unique identifier of the user
Request Body
Parameter Type Required Description
email string No New email address
name string No New display name
role string No New role slug
status string No New status: active, inactive, or pending
Example Request
PATCH /users/{user_id}
{
"email": "alice@[Link]",
"name": "Alice Müller",
"role": "admin",
"status": "active"
}
Code Samples
cURL
curl -X PATCH \
"[Link] \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "alice@[Link]",
"name": "Alice Müller",
"role": "admin",
"status": "active"
}'
Python
import requests
url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
payload = {
"email": "alice@[Link]",
"name": "Alice Müller",
"role": "admin",
"status": "active"
}
resp = [Link](url, headers=headers, json=payload)
print([Link]())
[Link]
const res = await fetch("[Link] {
method: "PATCH",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: [Link]({"email": "alice@[Link]", "name": "Alice Müller",
"role": "admin", "status": "active"}),
});
const data = await [Link]();
Response Fields
Field Type Description
id string Unique identifier for the user
email string Email address
name string Full display name
status string active, inactive, or pending
roles array Role slugs assigned to the user
created_at string ISO 8601 timestamp of when the user was created
Example Response
{
"id": "usr_7Hk2mP9qR",
"email": "alice@[Link]",
"name": "Alice Müller",
"status": "active",
"roles": [
"admin"
],
"created_at": "2025-03-15T09:41:00Z"
}
DELETE /users/{user_id} — Deactivate or Delete User
By default, sets the user's status to inactive and revokes all active sessions. Pass
hard_delete=true to permanently erase the user record instead — this cannot be undone.
Path Parameters
Field Type Description
user_id string Unique identifier of the user
Query Parameters
Parameter Type Required Description
hard_delete boolean No Permanently delete instead of deactivating (default: false)
Code Samples
cURL
curl -X DELETE \
"[Link] \
-H "Authorization: Bearer $API_KEY"
Python
import requests
url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = [Link](url, headers=headers)
print([Link]())
[Link]
const res = await
fetch("[Link] {
method: "DELETE",
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await [Link]();
Response Fields
Field Type Description
id string Unique identifier of the user
deleted boolean Whether the record was permanently deleted
status string Status after the operation
Example Response
{
"id": "usr_7Hk2mP9qR",
"deleted": false,
"status": "inactive"
}
Note: Deactivated users can be reactivated via PATCH by setting status to active. Hard-deleted users
cannot be recovered.
GET /users/{user_id}/roles — List User Roles
Returns the roles currently assigned to a user.
Path Parameters
Field Type Description
user_id string Unique identifier of the user
Code Samples
cURL
curl -X GET \
"[Link] \
-H "Authorization: Bearer $API_KEY"
Python
import requests
url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = [Link](url, headers=headers)
print([Link]())
[Link]
const res = await fetch("[Link] {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await [Link]();
Response Fields
Field Type Description
slug string Role identifier used in API requests
name string Human-readable role name
description string Summary of what the role can access
Example Response
{
"data": [
{
"slug": "admin",
"name": "Administrator",
"description": "Full access to all resources and settings"
}
],
"meta": {
"total": 1,
"page": 1,
"per_page": 20
}
}
POST /users/{user_id}/roles — Assign Role
Assigns an additional role to a user. Assigning a role does not remove existing roles — to replace a user's
roles entirely, use PUT /users/{user_id}.
Path Parameters
Field Type Description
user_id string Unique identifier of the user
Request Body
Parameter Type Required Description
role string Yes Role slug to assign, e.g. admin, editor, viewer
Example Request
POST /users/{user_id}/roles
{
"role": "admin"
}
Code Samples
cURL
curl -X POST \
"[Link] \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"role": "admin"
}'
Python
import requests
url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
payload = {
"role": "admin"
}
resp = [Link](url, headers=headers, json=payload)
print([Link]())
[Link]
const res = await fetch("[Link] {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: [Link]({"role": "admin"}),
});
const data = await [Link]();
Response Fields
Field Type Description
user_id string Unique identifier of the user
role string Role slug that was assigned
assigned_at string ISO 8601 timestamp of when the role was assigned
Example Response
{
"user_id": "usr_7Hk2mP9qR",
"role": "admin",
"assigned_at": "2026-06-10T09:00:00Z"
}
Roles & Permissions
Roles are organization-wide and grant a fixed set of permissions. Custom roles are not currently supported
— contact support to discuss enterprise requirements.
Slug Name Permissions
owner Owner Full access, including billing and organization deletion
admin Administrator Full access to all resources and settings
editor Editor Create and modify resources; cannot manage users or billing
viewer Viewer Read-only access to all resources
billing Billing Manager Access to invoices, plans, and payment methods only
SCIM Provisioning
The API implements the SCIM 2.0 core schema at /scim/v2, allowing identity providers to automatically
create, update, and deactivate users when they join or leave a group. SCIM requests authenticate with a
separate bearer token generated under Settings → SCIM Provisioning.
●
User provisioning maps the SCIM userName attribute to email.
●
Group membership changes are translated into role assignments via the role mapping configured in
the dashboard.
●
Deprovisioning a user via SCIM is equivalent to DELETE /users/{user_id} without
hard_delete.
Rate Limits & Quotas
The default rate limit is 500 requests per minute per organization. Current usage is reported via the
X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers.
Plan Requests Burst
Free 60 req/min 10
Team 500 req/min 100
Enterprise Custom Custom
Error Codes
Code HTTP Status Description
invalid_request 400 Missing or malformed parameters
authentication_error 401 Invalid or missing API token
permission_denied 403 Token does not have permission for this action
not_found 404 User or role does not exist
conflict 409 A user with this email already exists
rate_limit_exceeded 429 Too many requests, retry after the Retry-After header
server_error 500 Internal server error — contact support
Versioning & Changelog
Version Date Changes
v1.4 2026-04-02 Added SCIM 2.0 provisioning and the billing role
v1.3 2025-10-18 Added full-text search via the q query parameter
v1.2 2025-05-30 Added role assignment endpoints
v1.0 2024-08-01 Initial public release
SDKs & Client Libraries
Language Package Install
Python users-python pip install users-sdk
[Link] @org/users npm install @org/users
Ruby users-ruby gem install users-sdk
Go go-users go get [Link]/org/go-users
Java users-java implementation '[Link]:users-sdk:1.4.0'