The Users API allows tenant administrators to list existing users and invite new ones. User creation uses a privacy-safe response that does not reveal whether an email is already registered.
Base path
List users
Returns a paginated list of users for the current tenant, ordered by creation date (newest first). Only returns non-sensitive fields.
Query parameters
| Parameter | Required | Type | Description |
|---|
limit | No | integer | Maximum results per page. Default 25. |
cursor | No | string | Cursor for keyset pagination. |
Response 200
{
"data": [
{
"id": "usr_001",
"name": "Jane Smith",
"email": "jane@example.com",
"image": null,
"role": "admin",
"lastLoginAt": "2026-03-16T10:00:00.000Z",
"createdAt": "2026-02-01T12:00:00.000Z",
"updatedAt": "2026-03-16T10:00:00.000Z"
}
],
"pagination": {
"total": 5,
"limit": 25,
"hasMore": false,
"nextCursor": null
}
}
Invite a user
Creates a new user account for the tenant. If the email is already registered, the response is identical to a successful creation to prevent email enumeration.
Request body
| Field | Required | Type | Description |
|---|
email | Yes | string | Valid email address. |
name | No | string | null | User display name. |
role | No | enum | viewer (default), editor, admin. |
Example request
{
"email": "jane@example.com",
"name": "Jane Smith",
"role": "editor"
}
Response 201
{
"message": "If this email is not already registered, an account has been created."
}
The response message is intentionally vague for security. The same 201 status and message is returned regardless of whether the user already existed.
Error codes
| Code | Reason |
|---|
400 | Validation error (invalid email, invalid role). |
415 | Content-Type is not application/json. |
Role requirements
| Method | Minimum role |
|---|
| GET | admin |
| POST | admin |
