Authentication

Required headers, permissions, and authentication methods for the integration API.

All integration endpoints require authentication via an API key. JWT (user token) authentication is not supported on these endpoints.

Required header

Each request must include the following header:

Header	Value	Description
`x-api-key`	`rtn_sk_...`	API key generated from the administration panel

curl -X GET BASE_URL/api/integration/activities/tasks \
  -H "x-api-key: YOUR_API_KEY"

There is no need to send the x-tenant-id header. Each API key is associated with a specific tenant and the system resolves the tenant automatically from the key.

The API key is shown only once at creation time. If you lose it, you will need to revoke it and create a new one from the administration panel.

Obtaining an API key

Reten Environments

Environment	Admin Panel	API Base URL
Development	app-development.reten.ai	`https://api-development.reten.ai`
Staging	app-staging.reten.ai	`https://api-staging.reten.ai`
Production	app.reten.ai	`https://api.reten.ai`

Use the admin panel URL to manage API keys and dispatch configurations. Replace BASE_URL in code examples with the API base URL for your environment.

API keys are created from the Reten administration panel by a user with ADMIN role or higher:

Navigate to Settings → API Keys
Click Create API Key
Assign a descriptive name (e.g., "Task Dispatch — YOM")
Select the required permissions based on the endpoints you will use
Copy the generated key and store it securely

Permissions per endpoint

Each integration endpoint requires a specific permission on the API key:

Endpoint	Method	Required permission
`/api/integration/activities/tasks`	`GET`	`VIEW_ACTIVITIES`
`/api/integration/activity-results/tasks`	`POST`	`SUBMIT_ACTIVITY_RESULT`
`/api/integration/task-result-type-configs`	`GET`	`VIEW_ACTIVITIES`

An API key can only have permissions that are a subset of the permissions of the user who created it. If you need an additional permission, contact a tenant administrator.

Tenant scope

Each API key is associated with a single tenant. The system resolves the tenant automatically from the key — there is no need to send x-tenant-id:

If x-api-key is invalid or revoked → 401 Unauthorized response
If the key does not have the required permission → 403 Forbidden response
Returned data always corresponds to the key's tenant

User token vs API key

Feature	JWT (User token)	API Key
Primary use	Interactive sessions in the app	Programmatic integrations
Duration	15 minutes (access token)	No expiration (or configurable date)
Renewal	Automatic via refresh token	Not applicable — the key is permanent
Permissions	All permissions from the user's role	Subset selected at key creation
`x-tenant-id` header	Required	Not needed (tenant resolved from the key)
Integration endpoints	Not supported	Required

Endpoints under /api/integration/* only accept API key authentication. Requests with JWT will be rejected.