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

# Token Hierarchy

> Token types, scopes, lifecycle, and security model for Quint API authentication

Tokens authenticate non-interactive clients: agents reporting to the cloud, CI/CD pipelines querying the API, and scripts automating workflows. Each token has a type, a set of scopes, and a lifecycle.

## Token Types

| Type         | Prefix   | Purpose                                             | Created by             |
| ------------ | -------- | --------------------------------------------------- | ---------------------- |
| **Personal** | `qt_pk_` | Individual API access, scripting, local development | Any admin+ member      |
| **Service**  | `qt_sk_` | CI/CD pipelines, automated integrations, webhooks   | Any admin+ member      |
| **Deploy**   | `qt_dk_` | Agent-to-cloud authentication, device enrollment    | Admin+ or install flow |

### Personal Tokens

Tied to a specific user. When the user is removed from the org, their personal tokens are automatically revoked. Use these for:

* Local scripts and CLI tools
* Personal API exploration
* Development and testing

### Service Tokens

Org-scoped, not tied to any individual. Survive member departures. Use these for:

* CI/CD pipeline integration
* Automated alerting and reporting
* Third-party tool integration

### Deploy Tokens

Issued during device enrollment. Each agent instance gets its own deploy token. Use these for:

* Agent-to-cloud event streaming
* Heartbeat and status reporting
* Policy and configuration pulls

## Scopes

Every token carries one or more scopes that limit what it can do:

| Scope    | Allows                                          |
| -------- | ----------------------------------------------- |
| `read`   | Query events, sessions, scores, fleet status    |
| `ingest` | Submit events and telemetry (agents only)       |
| `manage` | Create/update policies, groups, profiles        |
| `admin`  | Team management, token operations, org settings |
| `*`      | All scopes (use sparingly)                      |

<Warning>
  Deploy tokens should only have `read` and `ingest` scopes. Granting `manage` or `admin` to a deploy token is a security risk -- a compromised agent could modify org-wide policies.
</Warning>

### Scope Combinations

Common patterns:

```
Agent deploy:     read + ingest
Read-only CI:     read
CI with policy:   read + manage
Admin automation: read + manage + admin
Full access:      *
```

## Lifecycle

<Steps>
  <Step title="Create">
    An admin or owner creates a token via the dashboard or API. The raw token is returned exactly once.
  </Step>

  <Step title="Store securely">
    The caller stores the raw token in a secrets manager, environment variable, or secure vault. Quint stores only the SHA-256 hash.
  </Step>

  <Step title="Use">
    Include the token in the `Authorization` header as a Bearer token. The API hashes the incoming token and looks up the hash.
  </Step>

  <Step title="Rotate">
    Create a new token with the same scopes, update your clients, then revoke the old token. There's no in-place rotation -- always create-then-revoke.
  </Step>

  <Step title="Revoke">
    Delete the token via dashboard or API. Takes effect immediately. Any in-flight request using the token will fail on the next call.
  </Step>
</Steps>

## Security Model

### Storage

```
Raw token:    qt_sk_a1b2c3d4e5f6...  (shown once, never stored)
Stored hash:  SHA-256(raw token)      (stored in database)
```

Quint never stores raw tokens. If you lose the token, you must create a new one.

### Authentication Flow

```
Client sends:  Authorization: Bearer qt_sk_a1b2c3d4e5f6...
                                │
API receives:  hash = SHA-256(token)
                                │
Database:      SELECT * FROM tokens WHERE hash = $1
                                │
Validation:    ├── Token exists?
               ├── Token not revoked?
               ├── Org active?
               └── Scope covers requested action?
```

### Token Metadata

Each token record stores:

| Field          | Description                                                    |
| -------------- | -------------------------------------------------------------- |
| `id`           | UUID primary key                                               |
| `org_id`       | Owning organization                                            |
| `created_by`   | User who created it (null for deploy tokens from install flow) |
| `kind`         | `personal`, `service`, or `deploy`                             |
| `scopes`       | Array of granted scopes                                        |
| `name`         | Human-readable label                                           |
| `hash`         | SHA-256 of the raw token                                       |
| `last_used_at` | Timestamp of most recent use                                   |
| `created_at`   | Creation timestamp                                             |
| `revoked_at`   | Revocation timestamp (null if active)                          |

<Tip>
  Use the `last_used_at` field to identify stale tokens. Tokens that haven't been used in 90+ days are candidates for revocation.
</Tip>

## API Usage

Create a token:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.quintai.dev/v1/tokens \
    -H "Authorization: Bearer $QUINT_JWT" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "CI Pipeline",
      "kind": "service",
      "scopes": ["read", "manage"]
    }'
  ```

  ```json Response theme={null}
  {
    "id": "tok_abc123",
    "name": "CI Pipeline",
    "kind": "service",
    "scopes": ["read", "manage"],
    "token": "qt_sk_a1b2c3d4e5f6g7h8i9j0...",
    "created_at": "2026-04-12T10:00:00Z"
  }
  ```
</CodeGroup>

<Note>
  The `token` field in the response is the raw token. Save it immediately. It will never appear again in any API response.
</Note>