> ## 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 and CLI device sessions |
| 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 browser/device authentication
Use browser/device authentication for interactive terminal and coding-agent
onboarding:
```bash theme={null}
akua auth login
akua auth status --json
```
The CLI opens Akua's device page and waits for you to approve the displayed
code. Use `akua auth login --no-browser` on a remote terminal and open the
displayed URL yourself. The CLI stores the resulting credential locally only
after approval.
The flow uses the
[OAuth 2.0 Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628),
so the CLI never handles your account password.
```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
```
MCP is optional. The [Platform MCP](/ai/platform-mcp) server has its own OAuth
flow and injects authentication server-side. A coding agent can complete
onboarding through the CLI without configuring MCP.
## 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.
Sign in, select workspace context, and run generated commands.
Download the spec and generate type-safe clients.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.