> ## Documentation Index
> Fetch the complete documentation index at: https://akua-1dce587a.mintlify.site/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

![Three credential types — a session token, an sk\_akua\_ workspace token, and an OAuth2 JWT — pass through a bearer checkpoint that verifies a hashed match, expiry, and workspace scope before reaching workspace resources; an out-of-scope request is rejected with 403](https://mintcdn.com/akua-1dce587a/AEEz0U2s7Do2sYaM/images/heros/api-authentication-light.svg?fit=max\&auto=format\&n=AEEz0U2s7Do2sYaM\&q=85\&s=872ea4964998aed405860e91bc089c29)

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
```

> [!NOTE]
>
> MCP is optional. The [Platform MCP](https://akua-1dce587a.mintlify.site/ai/platform-mcp.md) 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
}
```

> [!WARNING]
>
> 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.

> [!TIP]
>
> 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

> **[API introduction](https://akua-1dce587a.mintlify.site/apis/introduction.md)**
>
> Base URL, conventions, pagination, and error codes.

> **[API tokens reference](https://akua-1dce587a.mintlify.site/api-reference/api-tokens/list-api-tokens.md)**
>
> Manage workspace API tokens programmatically via the API reference.

> **[CLI](https://akua-1dce587a.mintlify.site/cli.md)**
>
> Sign in, select workspace context, and run generated commands.

> **[OpenAPI specification](https://akua-1dce587a.mintlify.site/apis/openapi.md)**
>
> Download the spec and generate type-safe clients.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.