Navigation
CX-Engine API · 5 min read

Users, Roles & Invitations

Manage workspace users, roles, organisations and user invitations via the API.

All endpoints in this section are workspace-scoped unless stated otherwise.

Headers: Authorization: Bearer {workspace-token}


#Users

#GET /api/users

Returns a paginated list of users in the workspace. Supports filtering and sorting.

Query parameters

Parameter Description
filter[name] Filter by name
filter[email] Filter by email
filter[phone] Filter by phone
filter[term] Full-text search
sort Sort field: id, name, email, created_at, updated_at. Prefix with - for descending (e.g. -created_at)
per_page Results per page (default: 20)
page Page number

Response 200 — paginated response

{
  "data": [
    {
      "id": 3,
      "name": "Bob Smith",
      "email": "bob@acme.com",
      "phone": "+33 1 00 00 00 00",
      "mobile_phone": null,
      "created_at": "2024-01-20T12:00:00Z",
      "updated_at": "2024-06-01T08:00:00Z"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 1
}

#GET /api/users/{id}

Returns a single user. Requires admin group permission.

Response 200 — user object

Response 403 — not authorized


#Roles

#GET /api/roles

Returns all roles defined in the workspace. Requires an admin user with the role.view permission (also required by GET /api/roles/{id}).

Response 200

[
  { "id": 1, "name": "manager", "permissions_count": 12 },
  { "id": 2, "name": "agent", "permissions_count": 5 }
]

#GET /api/roles/{id}

Returns a single role with its full permission list.

Response 200

{
  "permissions": ["customer.view", "customer.create", "customer.edit", ...],
  "id": 1,
  "team_id": 0,
  "name": "manager",
  "guard_name": "api",
  "created_at": "2024-01-10T08:00:00.000000Z",
  "updated_at": "2024-01-10T08:00:00.000000Z"
}

#Organisations

#GET /api/organisations

Returns all organisations in the workspace (the legal entities that own it), as a plain JSON array.

Response 200 — array of organisation objects

{
  "id": 1,
  "global_id": "b7f6c1d2-3e4a-4f5b-9c8d-0a1b2c3d4e5f",
  "tenant_id": "1b6feca6-cb4b-455e-a742-29e165e7446a",
  "name": "Acme Corp",
  "registration_number": "12345678900012",
  "tax_registration_number": "FR12345678900",
  "main_address_line_1": "10 rue de la Paix",
  "main_address_line_2": null,
  "main_address_post_code": "75002",
  "main_address_city": "Paris",
  "main_address_country": "France",
  "website": "https://acme.com",
  "created_at": "2024-01-10T08:00:00.000000Z",
  "updated_at": "2024-01-10T08:00:00.000000Z"
}

#GET /api/organisations/{id}

Returns a single organisation by ID.

Response 200 — organisation object


#PUT /api/organisations/{id}

Updates an organisation's details. The body must be a JSON object; only the fields you send are changed.

Requires an admin user with the organisation.edit permission.

Request body

Field Type Required Description
name string no Company name (2–255 characters)
registration_number string no Company registration number
tax_registration_number string no VAT number
main_address_line_1 string no Address line 1
main_address_line_2 string no Address line 2
main_address_post_code string no Post code
main_address_city string no City
main_address_country string no Country
website string no Website

id, global_id, tenant_id, created_at and updated_at cannot be set.

Response 201 — updated organisation object

Response 403 — the user is not an admin or lacks the organisation.edit permission


#User Invitations

Invitations are managed from the central API (sent to the central domain) for cross-workspace actions, or from the workspace API for workspace-level management.

#GET /api/user-invites (workspace)

Lists all pending invitations in the workspace.

Response 200 — array of invite objects


#POST /api/user-invites (workspace)

Sends an invitation to a user to join the workspace.

Request body

Field Type Required Description
email string yes Email address of the invitee
group string yes User group: admin or user
role string yes Role name (must exist in the workspace)
customer_id integer yes (if group=user) Customer the user will be linked to

Response 201

{
  "id": 8,
  "group": "user",
  "email": "newuser@example.com",
  "role": "agent",
  "customer_id": 12
}

Response 403 — cannot create admin invites without the required permission


#DELETE /api/user-invites/{id} (workspace)

Cancels a pending invitation.

Response 200

{ "response": "element deleted" }

#GET /api/user-invites/pending (central)

Returns all pending invitations sent to the currently authenticated user's email address, across all workspaces. Use this endpoint against the central domain.

Headers: Authorization: Bearer {central-token}

Response 200 — array of invite objects (token visible)


#GET /api/user-invites/{token}/inspect (central, unauthenticated)

Retrieves public information about a specific invitation without requiring authentication. Useful for pre-filling registration or login forms.

Response 200

{
  "invite": { "id": 8, "email": "newuser@example.com", "group": "user" },
  "workspace": { "name": "Acme Corp" },
  "exists": false
}

Response 400 — invite expired or no longer pending


#POST /api/user-invites/{token}/accept (central)

Accepts an invitation. The authenticated user is added to the workspace with the invited role.

Headers: Authorization: Bearer {central-token}

Response 200

{
  "message": "You have been successfully added to the workspace.",
  "workspace": { ... }
}

#POST /api/user-invites/{token}/decline (central)

Declines an invitation.

Headers: Authorization: Bearer {central-token}

Response 200

{ "response": "invite declined" }