Dixa User Management API Guide

Auth method: API Key (Bearer token) - a static API token issued per Dixa organization, passed as Authorization: Bearer

Setup steps

1. Log in to Dixa as an administrator.
2. Navigate to Settings → Integrations → API.
3. Generate a new API token; copy and store it securely.
4. Include the token in all requests as the HTTP header: Authorization: Bearer .

List agents

• Method: GET
• URL: https://dev.dixa.io/v1/agents
• Watch out for: Returns only active agents by default; pass ?active=false to include deactivated agents.

Request example

GET /v1/agents?limit=20 HTTP/1.1
Host: dev.dixa.io
Authorization: Bearer <token>

Response example

{
  "data": [
    {"id": "uuid", "email": "agent@co.com", "displayName": "Jane Doe", "role": "AGENT", "active": true}
  ],
  "nextPageToken": "abc123"
}

Get agent by ID

• Method: GET
• URL: https://dev.dixa.io/v1/agents/{agentId}
• Watch out for: Returns 404 if the agent ID does not exist or belongs to a different organization.

Request example

GET /v1/agents/uuid-1234 HTTP/1.1
Host: dev.dixa.io
Authorization: Bearer <token>

Response example

{
  "id": "uuid-1234",
  "email": "agent@co.com",
  "displayName": "Jane Doe",
  "role": "AGENT",
  "active": true
}

Create agent

• Method: POST
• URL: https://dev.dixa.io/v1/agents
• Watch out for: An invitation email is sent to the new agent automatically; there is no way to suppress this via the API.

Request example

POST /v1/agents HTTP/1.1
Host: dev.dixa.io
Authorization: Bearer <token>
Content-Type: application/json

{"email":"new@co.com","displayName":"New Agent","role":"AGENT"}

Response example

{
  "id": "uuid-5678",
  "email": "new@co.com",
  "displayName": "New Agent",
  "role": "AGENT",
  "active": true
}

Update agent

• Method: PATCH
• URL: https://dev.dixa.io/v1/agents/{agentId}
• Watch out for: Only fields included in the request body are updated (partial update semantics).

Request example

PATCH /v1/agents/uuid-5678 HTTP/1.1
Host: dev.dixa.io
Authorization: Bearer <token>
Content-Type: application/json

{"role":"TEAM_LEAD"}

Response example

{
  "id": "uuid-5678",
  "role": "TEAM_LEAD",
  "active": true
}

Deactivate agent

• Method: PATCH
• URL: https://dev.dixa.io/v1/agents/{agentId}
• Watch out for: Dixa does not support hard-deleting agents via the REST API; deactivation (active=false) is the supported offboarding method.

Request example

PATCH /v1/agents/uuid-5678 HTTP/1.1
Host: dev.dixa.io
Authorization: Bearer <token>
Content-Type: application/json

{"active":false}

Response example

{
  "id": "uuid-5678",
  "active": false
}

List teams

• Method: GET
• URL: https://dev.dixa.io/v1/teams
• Watch out for: Team membership is managed by updating the team object, not the agent object directly.

Request example

GET /v1/teams HTTP/1.1
Host: dev.dixa.io
Authorization: Bearer <token>

Response example

{
  "data": [
    {"id": "team-uuid", "name": "Support Team", "agentIds": ["uuid-1","uuid-2"]}
  ]
}

Add agent to team

• Method: POST
• URL: https://dev.dixa.io/v1/teams/{teamId}/agents
• Watch out for: Adding an agent to a team does not automatically assign them to the team's queues.

Request example

POST /v1/teams/team-uuid/agents HTTP/1.1
Host: dev.dixa.io
Authorization: Bearer <token>
Content-Type: application/json

{"agentId":"uuid-5678"}

Response example

{
  "teamId": "team-uuid",
  "agentId": "uuid-5678"
}

Get current authenticated agent (me)

• Method: GET
• URL: https://dev.dixa.io/v1/agents/me
• Watch out for: Returns the agent associated with the API token, not a caller identity; all tokens are org-level.

Request example

GET /v1/agents/me HTTP/1.1
Host: dev.dixa.io
Authorization: Bearer <token>

Response example

{
  "id": "uuid-owner",
  "email": "admin@co.com",
  "role": "ADMIN",
  "active": true
}

• Rate limits: Dixa enforces rate limits on the REST API; exact per-plan limits are not publicly documented in detail.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: When a rate limit is exceeded, Dixa returns HTTP 429. Clients should inspect response headers for limit context and implement exponential back-off. Specific numeric limits are not published in official docs as of the policy date.
• Pagination method: cursor
• Default page size: 20
• Max page size: 100
• Pagination pointer: pageToken / limit

• Webhooks available: Yes
• Webhook notes: Dixa supports webhooks for conversation and contact events. Agent/user lifecycle events (create, update, deactivate) are not explicitly listed as webhook triggers in official documentation.
• Alternative event strategy: Poll GET /v1/agents with a timestamp filter or use SCIM provisioning events via your IdP (Okta) for agent lifecycle notifications.
• Webhook events: conversation.created, conversation.assigned, conversation.closed, message.created, contact.created, contact.updated

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (Custom pricing)

• Endpoint: https://dev.dixa.io/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, POST /Groups, PATCH /Groups/{id}, DELETE /Groups/{id}, GET /Schemas, GET /ServiceProviderConfig

Limitations:

• SAML SSO must be configured and active before SCIM provisioning can be enabled.
• Only Okta is officially documented as a supported IdP for SCIM; Microsoft Entra ID and Google Workspace are not listed.
• SCIM Groups map to Dixa Teams; group-to-queue assignment is not managed via SCIM.
• Hard-delete via SCIM DELETE deactivates the agent rather than permanently removing the record.
• Schema discovery is supported via GET /Schemas endpoint.
• Requires Enterprise (Custom) plan - not available on Essential, Growth, or Ultimate tiers.

Three automation scenarios are well-supported by the API. For provisioning, POST /v1/agents creates the agent and triggers an invitation email automatically - suppression is not possible via the API.

Capture the returned agent id, then POST /v1/teams/{teamId}/agents to assign team membership; queue assignment requires a separate PATCH /v1/agents/{agentId} with queueIds. For offboarding, PATCH /v1/agents/{agentId} with {"active": false} deactivates the account; hard deletion is not supported via the REST API.

Open conversations are not automatically reassigned on deactivation, so a conversation reassignment step should precede the PATCH call. For full lifecycle automation, SCIM 2.

0 is available at https://dev.dixa.io/scim/v2 on the Enterprise plan with Okta as the only officially documented IdP; SAML SSO must be active before SCIM can be enabled. SCIM Groups map to Dixa Teams - not to Queues - so queue assignment remains outside SCIM scope and must be handled via the REST API.

Provision a new agent and assign to a team

1. POST /v1/agents with email, displayName, and role to create the agent (invitation email sent automatically).
2. Capture the returned agent id.
3. POST /v1/teams/{teamId}/agents with the new agentId to add them to the appropriate team.
4. Optionally PATCH /v1/agents/{agentId} to assign queueIds if queue assignment is needed.

Watch out for: The agent must accept the invitation email before they can log in; the API does not expose an 'invitation accepted' status field.

Offboard a departing agent

1. GET /v1/agents/{agentId} to confirm the agent exists and retrieve current team/queue assignments.
2. PATCH /v1/agents/{agentId} with {"active": false} to deactivate the account.
3. Reassign open conversations via the conversations API or Dixa UI before deactivation to avoid orphaned tickets.

Watch out for: Deactivation does not automatically reassign open conversations; unassigned conversations may fall into an unmonitored state.

Automate agent lifecycle via SCIM with Okta

1. Confirm Dixa Enterprise plan is active and SAML SSO is configured in Dixa Settings.
2. In Okta, add the Dixa SCIM application and configure the SCIM base URL (https://dev.dixa.io/scim/v2) and Bearer token.
3. Enable provisioning features: Create Users, Update User Attributes, Deactivate Users, Push Groups.
4. Assign Okta groups to the Dixa app; groups will sync as Dixa Teams via SCIM /Groups.
5. Test with a single user push before enabling for the full organization.

Watch out for: SCIM group push maps Okta groups to Dixa Teams, not to Dixa Queues. Queue assignment must still be managed manually or via the REST API.

Several non-obvious constraints can break integrations built against this API. Rate limit numeric thresholds are not publicly documented; the API returns HTTP 429 on breach, and clients must implement exponential back-off without a Retry-After header to guide timing.

The GET /v1/agents endpoint returns only active agents by default - omitting the ?active=false parameter will silently exclude deactivated agents from any identity graph sync, producing an incomplete picture of org membership.

SCIM provisioning has a hard dependency chain: Enterprise plan must be active and SAML SSO must be configured first; missing either condition blocks SCIM setup entirely. Microsoft Entra ID and Google Workspace are not officially supported IdPs for SCIM; teams not using Okta should treat SCIM integration as unsupported and untested.