Authentication

The Apollo API uses short-lived access tokens obtained from an OAuth 2.0 token endpoint. You exchange a credential once, then send the token on every request:

Authorization: Bearer <access_token>

Get an access token

Exchange your publishable key at the token endpoint. The endpoint itself is unauthenticated — the credential travels in the body:

cURL

curl -X POST "https://api-v3.aui.io/apollo-api/management/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "publishable_key",
    "publishable_key": "pk_..."
  }'

Response

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "agent_id": "6a344d186d3160971ec62eb6",
  "organization_id": "5f2b8c1a9d4e3f0012ab34cd"
}

string

The token to send as Authorization: Bearer <access_token>.

integer

Token lifetime in seconds. Request a new token when it expires — exchanges are cheap, so exchanging shortly before expiry is the simplest strategy.

string

The agent your messaging calls will run against. The token carries the agent, so messaging requests never include an agent_id in the body.

Your publishable key is issued in the AUI Console. Publishable keys are safe to use from client-side code — that’s what makes them “publishable” — and can additionally be restricted to allowed web origins and IP ranges.

Which credential for which surface

Surface	Paths	Accepted credentials
Messaging	`/messaging/v1/...`	Bearer token (from a publishable key)
Management	`/management/v1/...`	Bearer token (from a login session) or organization API key

Organization API key (management only)

Server-to-server management calls can skip the token flow and authenticate with your organization API key in a header:

curl "https://api-v3.aui.io/apollo-api/management/v1/projects" \
  -H "x-organization-api-key: <org_api_key>"

Unlike publishable keys, the organization API key must stay server-side. Never ship it in client code.

WebSocket authentication

The WebSocket session authenticates on the upgrade request with the same Bearer token:

GET wss://api-v3.aui.io/apollo-api/messaging/v1/session
Authorization: Bearer <access_token>

Invalid or expired credentials close the connection with WebSocket close code 1008 (policy violation). See WebSocket.

Failed authentication

Requests without a valid credential return 401 in the standard error envelope:

401

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials",
    "request_id": "req_..."
  }
}

Token-endpoint failures follow the OAuth 2.0 error convention instead:

400

{
  "error": "invalid_grant",
  "error_description": "invalid_publishable_key"
}

Best practices

Store credentials in environment variables

Keep keys out of source control.

export AUI_PUBLISHABLE_KEY="pk_..."

Reuse tokens for their lifetime

Exchange once and reuse the token until expires_in elapses rather than exchanging per request.

Scope keys to origins and IPs

If your publishable key is used from a browser, restrict it to your web origins in the Console so it can’t be replayed elsewhere.

​Get an access token

​Which credential for which surface

​Organization API key (management only)

​WebSocket authentication

​Failed authentication

​Best practices

Get an access token

Which credential for which surface

Organization API key (management only)

WebSocket authentication

Failed authentication

Best practices