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)

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.

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

1. Create

   An admin or owner creates a token via the dashboard or API. The raw token is returned exactly once.

2. Store securely

   The caller stores the raw token in a secrets manager, environment variable, or secure vault. Quint stores only the SHA-256 hash.

3. Use

   Include the token in the Authorization header as a Bearer token. The API hashes the incoming token and looks up the hash.

4. 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.

5. Revoke

   Delete the token via dashboard or API. Takes effect immediately. Any in-flight request using the token will fail on the next call.

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)

Use the last_used_at field to identify stale tokens. Tokens that haven’t been used in 90+ days are candidates for revocation.

API Usage

Create a token:

cURL

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"]
  }'

The token field in the response is the raw token. Save it immediately. It will never appear again in any API response.