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	CLI (default)
Workspace API token	sk_akua_...	CI/CD, scripts
OAuth2 JWT	eyJ... (JWT)	Custom integrations

For interactive CLI use, session tokens are the default (obtained via cnap auth login). For CI/CD and scripts, workspace API tokens are recommended.

CLI authentication

The fastest way to get started is with the CLI:

cnap auth login

This opens your browser where you approve the request, then the CLI stores a session token. No manual token management needed.

The CLI uses the OAuth 2.0 Device Authorization Grant to authenticate securely without handling your credentials directly.

The CLI stores your token in ~/.cnap/config.yaml. Run cnap auth status to check your current session.

Session tokens

When you run cnap auth login, the CLI stores a session token. Sessions are long-lived (1 year) and auto-refresh on every use, so active sessions effectively never expire.

If your session ever expires, log in again:

cnap auth login

Check your session status:

cnap auth status

Session tokens are ideal for interactive CLI use. For non-interactive environments (CI/CD, 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 CLI

cnap auth login --token sk_akua_...

This stores the given token directly in ~/.cnap/config.yaml.

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

CLI

# List the workspace's tokens
cnap auth tokens list

# Revoke a token
cnap auth tokens revoke <token-id>

curl

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

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 CLI stores your active workspace in ~/.cnap/config.yaml and sets Akua-Context automatically when needed. Switch workspaces with cnap workspaces switch.

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 via cnap auth logout.

Related topics

API introduction

Base URL, conventions, pagination, and error codes.

API tokens reference

Manage workspace API tokens programmatically via the API reference.

CLI reference

The Akua CLI and its auth commands.

OpenAPI specification

Download the spec and generate type-safe clients.