API Reference

The auth service runs on port 8001 and handles token lifecycle management. It is not called on the hot path — only for management operations. Base URL: http://localhost:8001 (dev) / AUTH_SERVICE_URL (production)

Health

`GET /health`

Health check endpoint. Response 200 OK:

{
  "status": "healthy",
  "service": "quint-auth"
}

Tokens

`POST /tokens/app`

Create an app token (management-plane root).

Request
Response 200

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production API",
  "scopes": ["*"],
  "ttl_days": 365
}

{
  "token": "qt_app_eyJhbGciOiJFUzI1NiIs...",
  "token_hash": "a1b2c3d4...",
  "jti": "unique-token-id",
  "expires_at": "2027-02-26T00:00:00Z"
}

`POST /tokens/bearer`

Derive a bearer token from an app token.

Request
Response 200

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "app_token_hash": "sha256-hash-of-app-token",
  "environment": "production",
  "ttl_days": 90
}

{
  "token": "qt_bearer_eyJhbGciOiJFUzI1NiIs...",
  "jti": "unique-token-id",
  "environment": "production",
  "expires_at": "2026-05-27T00:00:00Z"
}

`POST /tokens/agent`

Derive an agent token from a bearer token with RBAC policy.

Request
Response 200

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "bearer_jti": "jti-of-bearer-token",
  "agent_id": "code-review-agent",
  "agent_name": "Code Review Agent",
  "rbac": {
    "allowed_actions": ["data:read:*", "code:review:*"],
    "denied_actions": ["data:write:*"],
    "allowed_resources": ["repo:*"],
    "denied_resources": [],
    "max_sensitivity_level": 3
  },
  "ttl_hours": 24
}

{
  "token": "qt_agent_eyJhbGciOiJFUzI1NiIs...",
  "jti": "unique-token-id",
  "agent_id": "code-review-agent",
  "expires_at": "2026-02-27T00:00:00Z"
}

`POST /tokens/subagent`

Derive a subagent token from an agent token with permission narrowing.

Request
Response 200
Error 400

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "parent_agent_jti": "jti-of-agent-token",
  "agent_id": "lint-subagent",
  "agent_name": "Lint Subagent",
  "rbac": {
    "allowed_actions": ["code:read:*"],
    "denied_actions": ["data:write:*", "code:deploy:*"],
    "allowed_resources": ["repo:frontend"],
    "denied_resources": [],
    "max_sensitivity_level": 2
  },
  "ttl_hours": 4
}

{
  "token": "qt_subagent_eyJhbGciOiJFUzI1NiIs...",
  "jti": "unique-token-id",
  "agent_id": "lint-subagent",
  "delegation_depth": 1,
  "expires_at": "2026-02-26T04:00:00Z"
}

{
  "detail": "Subagent RBAC must be a subset of parent agent RBAC"
}

`POST /tokens/session`

Create a session token bound to an agent or subagent.

Request
Response 200

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "parent_jti": "jti-of-agent-or-subagent",
  "parent_type": "agent",
  "session_id": "session-2026-02-26-abc",
  "max_events": 1000,
  "ttl_minutes": 60
}

{
  "token": "qt_session_eyJhbGciOiJFUzI1NiIs...",
  "jti": "unique-token-id",
  "session_id": "session-2026-02-26-abc",
  "max_events": 1000,
  "expires_at": "2026-02-26T01:00:00Z"
}

`POST /tokens/override`

Create an ephemeral override token for a held high-risk event.

Request
Response 200

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "event-uuid",
  "allowed_decisions": ["approve", "reject"],
  "reason": "High-risk data access flagged by scoring pipeline",
  "ttl_minutes": 5
}

{
  "token": "qt_override_eyJhbGciOiJFUzI1NiIs...",
  "jti": "unique-token-id",
  "event_id": "event-uuid",
  "expires_at": "2026-02-26T00:05:00Z"
}

Revocation

`DELETE /tokens/{jti}`

Revoke a single token by JTI. Adds it to the bloom filter and revocation log. Response 200 OK:

{
  "jti": "revoked-token-jti",
  "status": "revoked"
}

`POST /revoke/cascade/{jti}`

Revoke a token and all tokens derived from it (children, grandchildren, etc.). Response 200 OK:

{
  "root_jti": "parent-token-jti",
  "revoked_count": 5,
  "revoked_jtis": ["jti1", "jti2", "jti3", "jti4", "jti5"]
}

`POST /bloom/rebuild`

Rebuild the bloom filter from the auth.revocation_log table. Used after Redis data loss or for periodic maintenance. Response 200 OK:

{
  "rebuilt": true,
  "entries": 1234
}

Signing Keys

`POST /keys/signing`

Generate a new ES256 signing key pair for a customer.

Request
Response 200

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "key_id": "key-uuid",
  "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "key_type": "ES256",
  "created_at": "2026-02-26T00:00:00Z"
}

`POST /keys/{key_id}/rotate`

Rotate a signing key — generates a new key and deactivates the old one. Request:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response 200 OK: Same as POST /keys/signing.

`GET /keys/public/{customer_id}`

Get the active public key for a customer. Used by the API service to populate its in-memory key cache. Response 200 OK:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "key_id": "key-uuid"
}

Webhooks

`POST /webhooks/register`

Request
Response 200

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "endpoint_url": "https://example.com/webhooks/quint"
}

{
  "webhook_id": "webhook-uuid",
  "endpoint_url": "https://example.com/webhooks/quint",
  "secret": "whsec_..."
}

Overrides

`POST /overrides/{event_id}/decide`

Submit an approve/reject decision for a held event using an override token.

Request
Response 200

{
  "override_token": "qt_override_eyJ...",
  "decision": "approve",
  "reason": "Authorized by team lead after review"
}

{
  "event_id": "event-uuid",
  "decision": "approve",
  "cosignature": "hmac-hex-string"
}

Error Responses

All error responses follow a consistent format:

{
  "detail": "Human-readable error message"
}

Status	Meaning
400	Bad request (invalid payload, permission escalation)
401	Authentication failed (expired, invalid, revoked token)
403	Authorization denied (RBAC violation)
404	Token or resource not found
429	Rate limit exceeded
503	Service unavailable (validator not initialized)

Auth Service

​Health

​GET /health

​Tokens

​POST /tokens/app

​POST /tokens/bearer

​POST /tokens/agent

​POST /tokens/subagent

​POST /tokens/session

​POST /tokens/override

​Revocation

​DELETE /tokens/{jti}

​POST /revoke/cascade/{jti}

​POST /bloom/rebuild

​Signing Keys

​POST /keys/signing

​POST /keys/{key_id}/rotate

​GET /keys/public/{customer_id}

​Webhooks

​POST /webhooks/register

​Overrides

​POST /overrides/{event_id}/decide

​Error Responses