API Authentication, Permissions, and Error Handling

The production API base address is typically https://<host>/api/v2. UTF-8 JSON is used by default, except for files, CAPTCHAs, SDP, and WebSockets.

flowchart LR
    A[Request carries API Token] --> B[Authenticate caller]
    B --> C[Check specific permission]
    C --> D[Run operation and return TraceId]
    D --> E[Handle HTTP status and error code]

Server-Side Integration Authentication

Administrators create API Tokens via interactive sessions. Tokens must be created separately for each system and not shared:

Authorization: Bearer ak_pat_<TOKEN>
Accept: application/json

When creating a token, set the purpose name, minimum permissions, expiration time, and optional IP CIDR. The full Token must not enter browser bundles, URLs, Git, screenshots, tickets, or general logs.

Common minimum permissions:

• Playback only: channels.view, streams.view, streams.play
• Query recordings: Add recordings.view, recordings.play
• Download recordings: Further add recordings.download
• Control device: devices.view, devices.control
• Intercom: Add devices.talk
• Monitoring acquisition: dashboard.view, nodes.view, system.view

Standard Tokens should not possess permissions for user, role, token management, or overall lifecycle management.

An administrator can expand a token under Access Control → API Token to inspect its effective permission codes, IP allowlist, and expiry, then edit them in place. Editing does not change the token string, but the new grant, IP range, and expiry apply immediately to later API calls, new playback connections, and lease renewals. Removing playback permission prevents old leases from renewing or reconnecting.

Browser Sessions

The WebUI uses ak_access, ak_refresh, and ak_csrf cookies. For write requests other than GET/HEAD/OPTIONS, the CSRF cookie value must also be placed in X-AK-CSRF. Refresh Tokens are rotated; replaying old values will be rejected.

Third-party backends should not simulate this login process. Third-party browser applications should not store long-lived Tokens in localStorage; use a same-origin application backend that proxies only the required operations for the current user.

HTTP Status

Security errors typically include code, message, and traceId, such as authentication_required, permission_denied, and csrf_invalid. Some business errors may use ProblemDetails or other structures; clients must preserve the Content-Type and original response and cannot assume all non-2xx responses are identical.

Retry Rules

• Network errors for GET can follow a backoff of 1, 2, 5, and 10 seconds.
• POST, PUT, and DELETE are not automatically replayed by default.
• After receiving 202, query the command instead of recreating it.
• For 409, query the current resource or active session first.
• A client timeout does not mean the server did not execute the request.

Swagger and Interface Catalog

Both Release and Debug versions can include Swagger/Knife4j, but their pages, resources, and OpenAPI JSON require an authenticated interactive WebUI session; regular API Tokens cannot enumerate the API documentation. Unattended integrations should use the OpenAPI files delivered with the version.

Token Rotation

First create and deploy the new Token, observe that the new credential is carrying traffic, and then revoke the old Token. After revocation, old values will fail immediately, and creation, usage summaries, and revocation actions will be visible in the audit logs.