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 |
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:
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:
Check your session 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_...
~/.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}'
{
"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
# List your tokens
cnap auth tokens list
# Revoke a token
cnap auth tokens revoke <token-id>
# 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"
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.
