User Management

These endpoints allow tenant administrators to manage users within their tenant. All requests require a valid Bearer token with admin privileges.

GET/auth/api/v1/tenant/users

List tenant users

Retrieve a paginated list of all users within the current tenant.

Query parameters

Name
page
Type
integer
Description
The page number to retrieve. Defaults to 1.
Name
per_page
Type
integer
Description
Number of users per page. Defaults to 15, maximum 100.
Name
search
Type
string
Description
Search users by name or email.
Name
type
Type
string
Description
Filter by user type: user, admin, or agent.

GET

/auth/api/v1/tenant/users

curl -G https://your-sphere.example.com/auth/api/v1/tenant/users \
  -H "Authorization: Bearer {token}" \
  -d page=1 \
  -d per_page=15

Response

{
  "data": [
    {
      "id": "9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "email": "alice@acme.com",
      "first_name": "Alice",
      "last_name": "Martin",
      "type": "user",
      "locale": "fr_FR",
      "timezone": "Europe/Paris",
      "provisioning_status": "completed",
      "created_at": "2026-01-15T10:30:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-890b-cdef-1234567890ab",
      "email": "bob@acme.com",
      "first_name": "Bob",
      "last_name": "Dupont",
      "type": "admin",
      "locale": "fr_FR",
      "timezone": "Europe/Paris",
      "provisioning_status": "completed",
      "created_at": "2026-01-10T08:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  }
}

GET/auth/api/v1/tenant/users/{id}

Get user details

Retrieve the full details of a specific user within the current tenant.

Path parameters

Name
id
Type
string
Description
The UUID of the user to retrieve.

GET

/auth/api/v1/tenant/users/{id}

curl https://your-sphere.example.com/auth/api/v1/tenant/users/9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "email": "alice@acme.com",
    "first_name": "Alice",
    "last_name": "Martin",
    "type": "user",
    "locale": "fr_FR",
    "timezone": "Europe/Paris",
    "provisioning_status": "completed",
    "provisioning_results": {
      "chat": "completed",
      "voip": "completed",
      "drive": "completed",
      "mail": "completed",
      "activity": "completed",
      "usermanager": "completed"
    },
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:31:00Z"
  }
}

POST/auth/api/v1/tenant/users

Create user

Create a new user within the current tenant. After creation, the user will be automatically provisioned across all active engines (chat, voip, drive, etc.).

Request body

Name
email
Type
string
Description
The email address for the new user. Must be unique within the tenant.
Name
password
Type
string
Description
The password for the new user. Minimum 8 characters.
Name
first_name
Type
string
Description
The user's first name.
Name
last_name
Type
string
Description
The user's last name.
Name
type
Type
string
Description
The user type. One of user, admin, or agent. Defaults to user.

POST

/auth/api/v1/tenant/users

curl -X POST https://your-sphere.example.com/auth/api/v1/tenant/users \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "charlie@acme.com",
    "password": "SecurePass123!",
    "first_name": "Charlie",
    "last_name": "Bernard",
    "type": "user"
  }'

Response

{
  "data": {
    "id": "c3d4e5f6-a7b8-90cd-ef12-34567890abcd",
    "email": "charlie@acme.com",
    "first_name": "Charlie",
    "last_name": "Bernard",
    "type": "user",
    "locale": "en_US",
    "timezone": "UTC",
    "provisioning_status": "pending",
    "created_at": "2026-02-20T14:00:00Z"
  }
}

PATCH/auth/api/v1/tenant/users/{id}

Update user

Update an existing user within the current tenant. Only the provided fields will be modified.

Path parameters

Name
id
Type
string
Description
The UUID of the user to update.

Request body

Name
first_name
Type
string
Description
The user's first name.
Name
last_name
Type
string
Description
The user's last name.
Name
type
Type
string
Description
The user type. One of user, admin, or agent.
Name
locale
Type
string
Description
The user's preferred locale.
Name
timezone
Type
string
Description
The user's timezone.

PATCH

/auth/api/v1/tenant/users/{id}

curl -X PATCH https://your-sphere.example.com/auth/api/v1/tenant/users/9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Alice",
    "last_name": "Martin-Dupont",
    "type": "admin"
  }'

Response

{
  "data": {
    "id": "9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "email": "alice@acme.com",
    "first_name": "Alice",
    "last_name": "Martin-Dupont",
    "type": "admin",
    "locale": "fr_FR",
    "timezone": "Europe/Paris",
    "provisioning_status": "completed",
    "updated_at": "2026-02-20T15:00:00Z"
  }
}

POST/auth/api/v1/tenant/users/{id}/provisioning

Trigger user provisioning

Trigger provisioning of a user across all active engines. This is useful when a user was created but provisioning did not complete, or when new engines have been activated since the user was created.

Provisioning registers the user in each engine (chat, voip, drive, mail, activity, usermanager) so they can access those services.

Path parameters

Name
id
Type
string
Description
The UUID of the user to provision.

POST

/auth/api/v1/tenant/users/{id}/provisioning

curl -X POST https://your-sphere.example.com/auth/api/v1/tenant/users/9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/provisioning \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "user_id": "9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "status": "processing",
    "engines": {
      "chat": "pending",
      "voip": "pending",
      "drive": "pending",
      "mail": "pending",
      "activity": "pending",
      "usermanager": "pending"
    }
  }
}

POST/auth/api/v1/tenant/users/{id}/reprovision

Re-provision failed engines

Re-provision a user for engines that previously failed. Only engines with a failed status will be retried. Engines that completed successfully are skipped.

Path parameters

Name
id
Type
string
Description
The UUID of the user to re-provision.

POST

/auth/api/v1/tenant/users/{id}/reprovision

curl -X POST https://your-sphere.example.com/auth/api/v1/tenant/users/9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/reprovision \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "user_id": "9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "status": "processing",
    "engines": {
      "chat": "skipped",
      "voip": "pending",
      "drive": "skipped",
      "mail": "pending",
      "activity": "skipped",
      "usermanager": "skipped"
    },
    "message": "Re-provisioning 2 failed engines"
  }
}

POST/auth/api/v1/tenant/users/{id}/promote-admin

Promote user to tenant admin

Promote a regular user to tenant admin. The user will receive the tenant.admin OAuth scope on their next login, allowing them to manage users in the tenant.

A tenant admin cannot promote themselves. If the user is already a tenant admin, a 409 is returned.

Path parameters

Name
id
Type
string
Description
The UUID of the user to promote.

POST

/auth/api/v1/tenant/users/{id}/promote-admin

curl -X POST https://your-sphere.example.com/auth/api/v1/tenant/users/9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/promote-admin \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "type": "admin-delegation",
    "id": "9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "attributes": {
      "email": "alice@acme.com",
      "is_tenant_admin": true
    }
  }
}

POST/auth/api/v1/tenant/users/{id}/demote-admin

Demote tenant admin

Demote a tenant admin back to a regular user. The user will lose the tenant.admin OAuth scope on their next login.

A tenant admin cannot demote themselves. If the user is not a tenant admin, a 409 is returned.

Path parameters

Name
id
Type
string
Description
The UUID of the tenant admin to demote.

POST

/auth/api/v1/tenant/users/{id}/demote-admin

curl -X POST https://your-sphere.example.com/auth/api/v1/tenant/users/9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/demote-admin \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "type": "admin-delegation",
    "id": "9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "attributes": {
      "email": "alice@acme.com",
      "is_tenant_admin": false
    }
  }
}