Authentication

Athena uses two types of API keys for external integrations:

Type	Prefix	Lifetime	Source	Use
Workspace API Key	wak_	Long-lived	Admin creates manually	Server-to-server
Ephemeral API Key	eak_	1 min – 24 h	Token exchange or server mint	Client-side sessions

Both are passed in the X-API-Key header. Never expose wak_ keys to client devices.

---

Token Exchange (Mobile / Web Apps)

Your app authenticates users through Firebase, Clerk, or a compatible provider. After authentication, exchange the provider’s ID token for an Athena eak_:

POST /auth/external/{workspace_id}
Content-Type: application/json

{
  "provider": "firebase",
  "token": "eyJhbGciOiJSUzI1NiIs..."
}

Supported providers: firebase (Google Firebase Auth), clerk.

Response (200):

{
  "data": {
    "key": "eak_a1b2c3d4e5f6...",
    "expires_at": "2026-05-13T12:00:00Z",
    "customer": {
      "id": "019f902b-db70-7ea4-8ef2-60a8ff5747cd",
      "external_id": "firebase_uid_xyz",
      "email": "user@example.com",
      "display_name": "Jane Doe",
      "active_credits": 100.0,
      "frozen_credits": 0.0,
      "inactive_credits": 0.0
    }
  }
}

The returned eak_ key is valid for 24 hours. Store it on the device and use it for all subsequent API calls via X-API-Key: eak_....

Rate limits on token exchange:

Scope	Limit
Per IP (before JWT verification)	10 / min, 50 / hr
Per identity (after JWT verification)	5 / min, 20 / hr

Error codes:

HTTP	Code	Cause
403	forbidden	External auth not enabled for this workspace
401	unauthorized	JWT verification failed (expired, invalid signature)
429	rate_limit	Rate limit exceeded — check Retry-After

Note

Token exchange also creates or updates the external_customer record. The customer’s credit balance and premium status are returned in every exchange response, so you can update your local cache without a separate call.

---

Server-Side Ephemeral Key Minting

For server-to-server flows, mint ephemeral keys directly without requiring a user JWT:

POST /ephemeral-keys/create
X-API-Key: wak_your_workspace_key
Content-Type: application/json

{
  "name": "user-session-12345",
  "purpose": "agent_execution",
  "scopes": ["agent:execute", "conversation:create"],
  "ttl_seconds": 3600,
  "agent_ids": [
    "019f902b-db6f-7ea4-8ef2-60a8ff5747cd",
    "019f902b-db71-7ea4-8ef2-60a8ff5747cd"
  ]
}

Field	Required	Description
name	Yes	Identifier for debugging / audit trail
purpose	Yes	agent_execution
scopes	Yes	Array of scope strings (see below)
ttl_seconds	Yes	60 – 86400 (1 min to 24 h)
agent_ids	No	Restricts key to specific agents. Empty = all agents.

Response:

{
  "data": {
    "key": "eak_xyz789...",
    "expires_at": "2026-05-13T01:00:00Z"
  }
}

Caution

The raw key value is returned once only. Store it immediately. There is no way to retrieve it later.

---

Scopes

Each eak_ key is minted with a set of scopes that define what it can do:

Scope	Access
agent:execute	Execute agents, upload attachments, check credit balance, manage push preferences, view notifications
conversation:create	Create conversations, archive conversations, send feedback, patch sticky variables. Implies conversation:read
conversation:read	Read conversation list and message history, read sticky variables
media:read	View generated media assets
attachment:read	View own uploads
ephemeral_key:create	Mint new ephemeral keys (requires wak_ only)
cms:read	Read CMS storefront content (public endpoints, no key required)

Default scopes issued by token exchange: agent:execute + conversation:create.

---

Key Renewal

eak_ keys expire. Your app should:

1. Track expires_at from the creation response.
2. Renew proactively before expiry (recommendation: renew when less than 5 minutes remain).
3. Handle 401 unauthorized responses by triggering re-authentication and retrying the failed request.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key"
  }
}

---

Using the X-API-Key Header

All authenticated requests require:

X-API-Key: eak_...
X-Workspace-Id: 019f58c6-0400-7fa2-a41f-a32abf613c76

The X-Workspace-Id header is required for API key paths. It must contain the workspace’s raw UUIDv7.

Missing or malformed workspace headers return 400 bad_request.

---

Security Best Practices

• Store wak_ keys only in server-side environment variables, never in client code, mobile bundles, or version control.
• Use short ttl_seconds for ephemeral keys — 3600 (1 hour) is recommended for most mobile sessions.
• Use agent_ids restriction when a session should only access specific agents.
• Monitor for 401 responses in production and alert on unexpected 403 (may indicate workspace misconfiguration).

---

Related Docs

• Quickstart — end-to-end example
• Execute — full execution endpoint reference
• Rate Limits — rate limits on auth endpoints
• Error Codes — full unauthorized / forbidden catalog