> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Key Setup

> Learn how to authenticate with the Xenia API using either a user token or client credentials.

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

```http theme={null}
Authorization: <your-token>
```

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

### Example

```http theme={null}
curl https://api.xenia.team/api/v1/task/workspaces/:workspaceId/tasks/catalog \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"
```

## 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. Go to Workspace Settings → API Access.
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.

<Note>
  This user will represent the API caller if x-client-user is not explicitly passed.
</Note>

Once created, you will get:

client key (name)

client secret (generated token)

You can create multiple client keys, each with a clear and descriptive name based on its specific purpose.

### Header Format

```http theme={null}
x-client-key: <your-client-key>
x-client-secret: <your-client-secret>
x-client-user: <optional-user-id>  # UUID of a user in the same workspace
```

* 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

```http theme={null}
curl https://api.xenia.team/api/v1/task/workspaces/:workspaceId/tasks/catalog \
  -X POST \
  -H "x-client-key: marketing-automation" \
  -H "x-client-secret: 3bd2f1e8a2b24f6a" \
  -H "x-client-user: 37d98201-9f3a-41fd-89b3-3be457c3f7ba" \
  -H "Content-Type: application/json" 
```

## Authentication Failures

If authentication fails, the API will return an error with status code 401

Make sure:

* Token or client credentials are valid
* Headers are correctly formatted and case-sensitive
* The x-client-user (if used) belongs to the correct 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:

* [**Locations API**](/api-reference/endpoints/locations/get-locations) - Manage your organization's locations
* [**Users API**](/api-reference/endpoints/users/get-users) - User management and HRIS integration
* [**Roles API**](/api-reference/endpoints/roles/get-roles) - Manage roles and customize permission structures
* [**Templates API**](/api-reference/endpoints/templates/get-templates) - Digital checklists and task management
* [**Submissions API**](/api-reference/endpoints/submission/get-submissions) - Access completed form data

## Support

Need help getting started? Contact us at [support@xenia.team](mailto:support@xenia.team).