Authentication

All AICA API endpoints require authentication (except the /health check). AICA supports three authentication methods depending on your integration context.

Clerk OAuth 2.0 (Primary)

AICA uses Clerk for user authentication and session management. This is the default method for browser-based applications.

1. Integrate the Clerk SDK into your frontend application.
2. Obtain a session token via getToken() from the Clerk client.
3. Pass the token in the Authorization header.

GET /api/v1/records
Authorization: Bearer <clerk_session_token>
X-Selected-Org-ID: org_xxxxx
Content-Type: application/json

Session tokens are short-lived and automatically refreshed by the Clerk SDK.

Multi-Tenancy

AICA is multi-tenant. All organization-scoped requests must include the X-Selected-Org-ID header:

X-Selected-Org-ID: org_2a8b9c1d

Omitting this header on org-scoped endpoints returns a 400 Bad Request.

API Token Authentication

For server-to-server integrations, CI/CD pipelines, or automated workflows, use a long-lived API token.

Generating a Token

1. Navigate to Settings > API Keys in the AICA dashboard.
2. Click Create API Key.
3. Copy the token immediately — it is shown only once.
4. Store it securely (environment variable, secrets manager).

Using the Token

GET /api/v1/records
Authorization: Bearer aica_sk_xxxxxxxxxxxxxxxxxxxxx
X-Selected-Org-ID: org_xxxxx
Content-Type: application/json

API tokens inherit the permissions of the user who created them. Revoke tokens from the same settings page.

Embedded Authentication (Bitrix24)

When AICA runs as an embedded app inside Bitrix24, authentication uses cookie-based sessions initialized from the CRM context.

Flow

1. The Bitrix24 iframe loads the AICA embedded app.
2. The app sends B24 frame data to the authentication endpoint:

POST /api/v1/embedded/auth
Content-Type: application/json

{
  "domain": "your-company.bitrix24.com",
  "memberId": "abc123",
  "authId": "def456",
  "refreshId": "ghi789"
}

3. AICA validates the data against Bitrix24 and sets a secure session cookie.
4. Subsequent requests are authenticated via the cookie — no Authorization header needed.

See the Bitrix24 Integration Guide for full setup instructions.

Standard Request Format

GET /api/v1/records?page=1&pageSize=20
Authorization: Bearer <token>
X-Selected-Org-ID: org_xxxxx
Content-Type: application/json

Error Responses

Status	Meaning	Common Cause
401 Unauthorized	Invalid or expired token	Token missing, malformed, or expired. Refresh session or generate a new API key.
403 Forbidden	Valid token, insufficient permissions	User lacks the required role for the requested action. Check RBAC settings.
429 Too Many Requests	Rate limit exceeded	More than 200 requests/minute. Back off and retry with exponential delay.

401 Response Example

{
  "error": {
    "message": "Invalid or expired authentication token",
    "code": "UNAUTHORIZED"
  }
}

429 Response Example

The Retry-After header indicates how many seconds to wait before retrying:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "error": {
    "message": "Rate limit exceeded. Try again in 30 seconds.",
    "code": "RATE_LIMITED"
  }
}