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 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 so the CLI can authenticate without handling your credentials directly.

For agent-based workflows, use the 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). 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 preview

Akua CLI status and supported automation alternatives.

OpenAPI specification

Download the spec and generate type-safe clients.

Overview

Endpoints

CLI authentication preview

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 preview

OpenAPI specification

​CLI authentication preview

​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 preview

OpenAPI specification

CLI authentication preview

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