Users

User management is essential for controlling access and permissions within your customer account. On this page, we will dive into the read-only user management endpoints you can access programmatically with an API key. We will look at how to query users and list the roles that can be assigned to them within your customer context. All endpoints are scoped to your customer account via the {customer_slug} path parameter. Authenticate with an API key created in the customer portal under Settings → API Keys, sent as Authorization: Bearer xn_... (or alternatively in an X-API-Key header).

The user model

The user model contains the information about users in your customer account that is exposed through the API, including their account status, profile names, and role assignments within your customer context.

Properties

Name
user_id
Type
uuid
Description
Unique identifier for the user.
Name
email
Type
string
Description
User's email address. Unique across the platform.
Name
is_active
Type
boolean
Description
Whether the user account is active.
Name
account_locked
Type
boolean
Description
Whether the user account is locked.
Name
last_login
Type
timestamp
Description
Timestamp of the user's last login (nullable).
Name
created_at
Type
timestamp
Description
Timestamp when the user was created.
Name
updated_at
Type
timestamp
Description
Timestamp when the user was last updated.
Name
customer_role
Type
string
Description
First assigned role name, kept for backwards compatibility — prefer roles (nullable).
Name
status
Type
string
Description
Current status of the user: "active", "inactive", or "locked".
Name
first_name
Type
string
Description
User's first name, from their profile (nullable).
Name
last_name
Type
string
Description
User's last name, from their profile (nullable).
Name
roles
Type
array
Description
All roles assigned to the user within your customer account. Each entry is an object with role_id (uuid) and name (string). In list responses, roles is instead a flat array of role name strings.

GET/customers/{customer_slug}/users/available-roles

Available roles

This endpoint allows you to retrieve all roles that can be assigned to users within your customer account. The result includes platform default roles (where customer_id is null) as well as roles created specifically for your customer.

Path parameters

Name
customer_slug
Type
string
Description
The unique slug identifier for the customer account.

Request

GET

/customers/{customer_slug}/users/available-roles

curl https://api.xnumbers.io/api/customers/acme/users/available-roles \
  -H "Authorization: Bearer {token}"

Response

[
  {
    "role_id": "550e8400-e29b-41d4-a716-446655440010",
    "name": "Customer Admin",
    "description": "Full administrative access within the customer account",
    "customer_id": null,
    "is_system_role": true,
    "user_type": "customer",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z"
  },
  {
    "role_id": "550e8400-e29b-41d4-a716-446655440011",
    "name": "Support Agent",
    "description": "Custom role for support staff",
    "customer_id": "550e8400-e29b-41d4-a716-446655440099",
    "is_system_role": false,
    "user_type": "customer",
    "created_at": "2024-02-10T09:00:00.000Z",
    "updated_at": "2024-02-10T09:00:00.000Z"
  }
]

GET/customers/{customer_slug}/users

List all users

This endpoint allows you to retrieve a paginated list of all users under the specified customer account. By default, a maximum of ten users are shown per page, sorted by email. The pagination metadata includes per-status counts across all users in the account, regardless of the active status filter.

Path parameters

Name
customer_slug
Type
string
Description
The unique slug identifier for the customer account.

Query parameters

Name
page
Type
integer
Description
Page number for pagination (default: 1, min: 1).
Name
limit
Type
integer
Description
Number of users per page (default: 10, min: 1).
Name
search
Type
string
Description
Search term to filter users by email (case-insensitive, partial match).
Name
status
Type
string
Description
Filter users by status. Accepts one or more comma-separated values of "active", "inactive", "locked" (e.g. status=active,locked).

Request

GET

/customers/{customer_slug}/users

curl -G https://api.xnumbers.io/api/customers/acme/users \
  -H "Authorization: Bearer xn_your_api_key" \
  -d limit=10 \
  -d page=1 \
  -d status=active \
  -d search=jane

Response

{
  "data": [
    {
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "roles": ["Customer Admin"],
      "status": "active",
      "last_login": "2024-01-15T14:30:00.000Z",
      "account_locked": false,
      "customer_role": "Customer Admin"
    },
    {
      "user_id": "550e8400-e29b-41d4-a716-446655440001",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "roles": ["Support Agent"],
      "status": "active",
      "last_login": null,
      "account_locked": false,
      "customer_role": "Support Agent"
    }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "limit": 10,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "status_counts": {
      "active": 20,
      "inactive": 3,
      "locked": 2
    }
  }
}

GET/customers/{customer_slug}/users/{user_id}

Retrieve a user

This endpoint allows you to retrieve detailed information for a specific user within your customer account, including all of their role assignments.

Path parameters

Name
customer_slug
Type
string
Description
The unique slug identifier for the customer account.
Name
user_id
Type
uuid
Description
The unique identifier for the user.

Request

GET

/customers/{customer_slug}/users/{user_id}

curl https://api.xnumbers.io/api/customers/acme/users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}"

Response

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "jane.smith@example.com",
  "is_active": true,
  "account_locked": false,
  "last_login": "2024-01-15T14:30:00.000Z",
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-15T09:00:00.000Z",
  "customer_role": "Customer Admin",
  "status": "active",
  "first_name": "Jane",
  "last_name": "Smith",
  "roles": [
    {
      "role_id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Customer Admin"
    }
  ]
}