Authentication, scope, and rate limits

Overview

• Agent tokens (sk_agt_...) are created by the account owner via the app or token-management APIs. One token per user; multiple agents can share it.
• Token management (create, rotate, revoke, status) uses user JWT and is not callable with an agent token.
• Agent APIs (e.g. job descriptions) accept only agent tokens; requests with a user JWT are rejected with 403.

Authentication

User JWT (token management)

Used for GET/POST/DELETE /api/agent-tokens/.... Obtained via normal login (e.g. /api/auth/login). Send as:

Authorization: Bearer <JWT>

Agent token (agent APIs)

Used for all paths under /api/agent/. Send as:

Authorization: Bearer sk_agt_<64 hex characters>

• Format: Prefix sk_agt_ + 64 hex characters.
• Verification: Gateway hashes the token (SHA256) and looks up user_settings.agent_api_token_hash. Invalid or revoked tokens receive 401 Unauthorized.

Scope

• Agent tokens may only call paths under /api/agent/.
• Requests with an agent token to any other path (e.g. /api/job-descriptions/, /api/auth/, /api/ai-coach/) return:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "detail": "Agent tokens are restricted to /api/agent/ endpoints.",
  "error": "agent_scope_violation"
}

Rate limits

When exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>
X-RateLimit-Limit: <limit>
X-RateLimit-Remaining: 0
X-RateLimit-Reset: <unix timestamp>

{
  "detail": "Global rate limit exceeded. Please try again later.",
  "error": "rate_limit_exceeded",
  "retry_after": <seconds>
}

Error format and status codes

• 401 Unauthorized: Missing or invalid Authorization (JWT or agent token). Body often includes "detail": "Invalid or revoked agent token" or similar.
• 403 Forbidden: Agent token used on a non-agent path (agent_scope_violation), or user JWT used on an agent-only endpoint.
• 404 Not Found: Resource not found (e.g. job description ID for misalignment report).
• 422 Unprocessable Entity: Validation error (e.g. missing required fields). Body is typically the framework's validation error shape.
• 429 Too Many Requests: Rate limit exceeded. Use Retry-After and X-RateLimit-* headers.
• 500 Internal Server Error: Server or dependency failure. Body may include a detail message.