> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cnap.tech/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
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](https://datatracker.ietf.org/doc/html/rfc8628) to authenticate securely without handling your credentials directly.

```mermaid theme={null}
sequenceDiagram
    participant CLI
    participant Browser
    participant CNAP

    CLI->>CNAP: Request device code
    CNAP-->>CLI: Device code + user code
    CLI->>Browser: Open verification URL
    Note over CLI: "Enter code: ABCD-EFGH"
    Browser->>CNAP: User approves
    CLI->>CNAP: Poll for token
    CNAP-->>CLI: Session token
    Note over CLI: Stored in ~/.cnap/config.yaml
```

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

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

```bash theme={null}
cnap auth login
```

Check your session status:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "id": "j572abc123def456",
  "name": "CI pipeline",
  "token": "cnap_pat_abc123...",
  "expires_at": 1734567890000
}
```

<Warning>
  The `token` field is only returned once at creation time. Store it securely — it cannot be retrieved later.
</Warning>

### List and revoke tokens

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # List your tokens
    cnap auth tokens list

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

  <Tab title="curl">
    ```bash theme={null}
    # 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_..."
    ```
  </Tab>
</Tabs>

## Workspace Scoping

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

```bash theme={null}
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.

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

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