Authentication

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

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:

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, so the CLI never handles your account password.

MCP is optional. The 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). 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:

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:

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

# 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:
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:
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.

API introduction

Base URL, conventions, pagination, and error codes.

API tokens reference

Manage workspace API tokens programmatically via the API reference.

CLI

OpenAPI specification

Download the spec and generate type-safe clients.

Overview

Endpoints

CLI browser/device authentication

Session tokens

Workspace API tokens

Create a token via the dashboard

Create a token via the API

List and revoke tokens

Workspace scoping

Security

API introduction

API tokens reference

CLI

OpenAPI specification

​CLI browser/device authentication

​Session tokens

​Workspace API tokens

​Create a token via the dashboard

​Create a token via the API

​List and revoke tokens

​Workspace scoping

​Security

​Related topics

API introduction

API tokens reference

CLI

OpenAPI specification

CLI browser/device authentication

Session tokens

Workspace API tokens

Create a token via the dashboard

Create a token via the API

List and revoke tokens

Workspace scoping

Security

Related topics