Skip to main content
To keep your workspace secure and enable flexible integrations, we support two authentication methods:
  1. Token-based Authentication – For user-specific access (e.g., web or mobile apps)
  2. Client Credentials Authentication – For public or system-level integrations using workspace-scoped credentials
Every API request must be authenticated using one of these methods. This page explains how to get started with each.

​
1. Token-based Authentication

This method is for users who log in to Xenia via the UI or mobile app and need to access protected endpoints.

​
Flow Overview

  1. A user logs in using the login endpoint.
  2. The system returns a token if credentials are valid.
  3. The token is then passed in every API request via the Authorization header.

​
Header Format

⚠️ Do not prefix the token with Bearer. The token should be passed directly as a raw string.

​
Example

​
2. Client Credentials Authentication (Public APIs)

Use this method when you want to integrate with Xenia on behalf of a workspace — for automations, backend services, or 3rd-party integrations.

​
Setup Instructions

  1. In the Xenia web app, open Settings → Public Integrations (this is an add-on capability — if you don’t see it, contact your Xenia representative to enable it for your workspace). Creating keys requires the Manage API Access Keys permission, granted to workspace Owners by default.
  2. Click Create Client Key.
  3. Assign a clear and descriptive label to the client key (e.g., “marketing-automation”) that reflects its specific purpose.
  4. Choose a default user from your workspace. The key’s data access, and which endpoints it can call, are governed by that user’s role and location access.
This user will represent the API caller if x-client-user is not explicitly passed.
Once created, you will get:
  • client key (the name/identifier you chose)
  • client secret (a generated token, shown only once — copy and store it securely; it cannot be retrieved later)
You can create multiple client keys, each with a clear and descriptive name based on its specific purpose. Each key is permanently tied to the workspace it was created in and can only access that workspace’s data.

​
Header Format

  • x-client-user is optional.
  • If not provided, API acts as the default user tied to that key.
  • If provided, API will impersonate that user (must belong to the same workspace).

​
Example

Each header also has a query-string equivalent (?token=, ?clientKey=, ?clientSecret=, ?clientUser=) for tools that can’t set custom headers. Headers are preferred.

​
What a client key can call

Client keys can only reach a specific allow-listed set of endpoints — the ones documented in this API Reference (reads, user lifecycle, task reads and writes, project reads and lifecycle control, reporting, and the Enterprise Locations bulk writes). Calling any other route with a client key returns:
Each allow-listed route still enforces its own permission on the key’s user (e.g. CAN_VIEW_REPORTING, CAN_MANAGE_USERS), so use a default user whose role grants the access your integration needs. Some routes additionally require a feature on the workspace (for example Public API, Advanced Dashboards, Advanced Location Based Assignment, or Location Attributes) — those are called out on the endpoint page, and a missing feature also returns 403.

​
Two path shapes

Several management endpoints are registered under two paths, and both are allow-listed:
  • a workspace-scoped form — PATCH /api/v1/mgt/workspaces/{workspaceId}/users/{userId}/role
  • a shorter form without the workspace segment — PATCH /api/v1/mgt/users/{userId}/role
They behave identically. Because a client key is bound to exactly one workspace, the shorter form resolves the workspace from the key, and the workspace-scoped form must name that same workspace. The user-lifecycle endpoints appear in both shapes across this documentation — the reference pages use the workspace-scoped form, the User Lifecycle guide uses the shorter one. Pick either. Where an endpoint page shows only one shape (for example the Enterprise Locations endpoints, which are workspace-scoped only), use the shape shown.

​
Authentication Failures

If authentication fails, the API returns HTTP 401, for example:
Make sure:
  • Token or client credentials are valid (401 Invalid client credentials means the key/secret is wrong or the key was deactivated)
  • Headers are correctly formatted and case-sensitive
  • The x-client-user (if used) belongs to the correct workspace (otherwise 401 User not found in the workspace)

​
Best Practices

  • Keep your client secrets secure and never expose them in frontend code.
  • Use one key per use-case to isolate integrations.
  • Rotate credentials periodically.
  • Use token-based auth for logged-in users (mobile/web).
  • Use client credentials for integrations and automation.

​
Next Steps

Now that you’re authenticated and can make requests, explore the API documentation:

​
Support

Need help getting started? Contact us at support@xenia.team.