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"
}

access_token

string

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

expires_in

integer

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

agent_id

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