> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication
> Authenticate with the Akua API using session tokens, workspace API tokens, or JWTs
Every API request requires an `Authorization: Bearer` header with a valid token.
| Method | Format | Best for |
| ------------------- | --------------------- | --------------------------------------- |
| Session token | 32-char random string | Dashboard sessions and future CLI flows |
| Workspace API token | `sk_akua_...` | CI/CD, scripts |
| OAuth2 JWT | `eyJ...` (JWT) | Custom integrations |
For CI/CD and scripts, **workspace API tokens** are recommended.
## CLI authentication preview
The Akua CLI authentication flow is part of the CLI preview and is not the public onboarding path yet. Use workspace API tokens for scripts, or connect an MCP-compatible agent when you want an assistant to act on your behalf.
The preview design uses the [OAuth 2.0 Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628) so the CLI can authenticate without handling your credentials directly.
```mermaid theme={null}
sequenceDiagram
participant CLI
participant Browser
participant Akua
CLI->>Akua: Request device code
Akua-->>CLI: Device code + user code
CLI->>Browser: Open verification URL
Note over CLI: "Enter code: ABCD-EFGH"
Browser->>Akua: User approves
CLI->>Akua: Poll for token
Akua-->>CLI: Session token
Note over CLI: Stores session state
```
For agent-based workflows, use the [Platform MCP](/ai/platform-mcp) server. It handles OAuth and injects auth server-side, so the agent cannot read your token.
## Session tokens
Session tokens back browser-approved interactive sessions. Sessions are long-lived and auto-refresh on use, so active sessions effectively never expire.
For non-interactive environments such as CI/CD and scripts, use workspace API tokens instead.
## Workspace API tokens
Workspace API tokens are long-lived tokens prefixed with `sk_akua_`. They're the recommended approach for CI/CD pipelines, scripts, and automated workflows.
A token belongs to a **workspace**, not a user. The workspace it's created in is the workspace it acts on — calls made with a workspace API token operate on that workspace implicitly, with no extra header required (see [Workspace scoping](#workspace-scoping)). Creating and revoking tokens is gated by the workspace **owner** or **admin** role.
### Create a token via the dashboard
Create workspace API tokens from the Akua dashboard under **Workspace settings > API tokens** (owner or admin only).
### Create a token via the API
If you already have a valid token, you can create additional workspace API tokens programmatically:
```bash theme={null}
curl -X POST https://api.akua.dev/v1/api_tokens \
-H "Authorization: Bearer $AKUA_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "CI pipeline", "expires_at": 1742169600}'
```
Response:
```json theme={null}
{
"id": "j572abc123def456",
"name": "CI pipeline",
"token": "sk_akua_abc123...",
"expires_at": 1734567890000
}
```
The `token` field is only returned once at creation time. Store it securely — it cannot be retrieved later.
### List and revoke tokens
```bash theme={null}
# List the workspace's tokens
curl https://api.akua.dev/v1/api_tokens \
-H "Authorization: Bearer $AKUA_API_TOKEN"
# Revoke a token
curl -X DELETE https://api.akua.dev/v1/api_tokens/TOKEN_ID \
-H "Authorization: Bearer $AKUA_API_TOKEN"
```
Replace `TOKEN_ID` with the token ID to revoke.
## Workspace scoping
Many endpoints operate within a workspace context. How the workspace is selected depends on the credential:
* **Workspace API token** — the token already belongs to a workspace, so that workspace is used automatically. No extra header is needed:
```bash theme={null}
curl https://api.akua.dev/v1/installs \
-H "Authorization: Bearer $AKUA_API_TOKEN"
```
* **Broad credential** (dashboard session or a multi-workspace token) — select the target workspace with the optional `Akua-Context` header:
```bash theme={null}
curl https://api.akua.dev/v1/installs \
-H "Authorization: Bearer $AKUA_API_TOKEN" \
-H "Akua-Context: ws_xxx"
```
If a broad credential calls a workspace-scoped endpoint without `Akua-Context`, the request returns `403 Forbidden` — the workspace is required and the request is ambiguous. If you send an `Akua-Context` that names a different workspace than the token already belongs to, you'll also receive a `403 Forbidden`. A matching `Akua-Context` is accepted but redundant.
The Platform MCP server handles request auth for agents. For direct API calls with broad credentials, set `Akua-Context` explicitly.
## Security
* Akua **never stores plaintext tokens**. Tokens are hashed before storage.
* Tokens can have an **expiration date**. Expired tokens are rejected automatically.
* Each token tracks its **last used** timestamp for auditing.
* Revoked tokens are deleted immediately and cannot be recovered.
* Session tokens are validated server-side on every request and can be revoked from the issuing surface.
## Related topics
Base URL, conventions, pagination, and error codes.
Manage workspace API tokens programmatically via the API reference.
Akua CLI status and supported automation alternatives.
Download the spec and generate type-safe clients.