Authentication

Authenticate with the CNAP API

Every API request requires an Authorization: Bearer header with a valid token.

Method	Format	Best for
Session token	32-char random string	CLI (default)
Personal Access Token	cnap_pat_...	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, Personal Access Tokens (PATs) 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, just 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 Personal Access Tokens instead.

Personal Access Tokens

PATs are long-lived tokens prefixed with cnap_pat_. They’re the recommended approach for CI/CD pipelines, scripts, and automated workflows.

Create a token via the CLI

cnap auth login --token cnap_pat_...

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

Create a token via the dashboard

You can also create PATs from the CNAP dashboard at Account > Access Tokens.

Create a token via the API

If you already have a valid token, you can create additional PATs programmatically:

curl -X POST https://api.cnap.tech/v1/user/tokens \
  -H "Authorization: Bearer cnap_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "CI pipeline", "expires_at": 1742169600}'

Response:

{
  "id": "j572abc123def456",
  "name": "CI pipeline",
  "token": "cnap_pat_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 your tokens
cnap auth tokens list

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

curl

# List your tokens
curl https://api.cnap.tech/v1/user/tokens \
  -H "Authorization: Bearer cnap_pat_..."

# Revoke a token
curl -X DELETE https://api.cnap.tech/v1/user/tokens/<token-id> \
  -H "Authorization: Bearer cnap_pat_..."

Workspace Scoping

Many endpoints operate within a workspace context. Pass the workspace ID via the X-Workspace-Id header:

curl https://api.cnap.tech/v1/installs \
  -H "Authorization: Bearer cnap_pat_..." \
  -H "X-Workspace-Id: j575xyz789ghi012"

If the header is missing on a workspace-scoped endpoint, the request will succeed but may return limited results. If the specified workspace ID is invalid or you’re not a member, you’ll receive a 403 Forbidden error.

The CLI stores your active workspace in ~/.cnap/config.yaml and sends it automatically. Switch workspaces with cnap workspaces switch.

Security

• CNAP never stores plaintext tokens. PATs are hashed before storage.
• PATs can have an expiration date. Expired tokens are rejected automatically.
• Each PAT 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.