Authentication & API Keys
Create Vitae API keys, authenticate requests securely, rotate keys, and avoid common auth mistakes in production.
Vitae supports Bearer authentication. You can authenticate with a user JWT token or a service-style API key (vtk_...). This page explains when to use each mode, how to rotate keys safely, and how to debug auth failures quickly.
Auth model overview
- JWT bearer: best for first-party app sessions and user-context operations.
- API key bearer: best for backend integrations, agents, and automation jobs.
Header format
Authorization: Bearer vtk_YOUR_API_KEYAPI key lifecycle
Create
Create a dedicated key per integration so you can revoke one system without breaking all systems.
Rotate
Create a new key, deploy it, verify traffic with the new key, then revoke the old key. Never rotate by deleting first.
Revoke
Immediately revoke keys that were leaked, copied into logs, or committed by mistake.
Security checklist
- Store keys in server-side secret manager only
- Never expose API keys in browser JavaScript bundles
- Rotate keys on a fixed schedule
- Use distinct keys for dev, staging, and production
Authentication error matrix
Error matrix
| Status | Likely cause | How to fix | Retry? |
|---|---|---|---|
| 401 | Missing, malformed, or invalid bearer token | Verify Authorization header and token value | no |
| 403 | Account tier or access policy does not allow endpoint usage | Confirm plan tier and endpoint permissions | no |
Common mistakes
Using API keys from frontend browser code
API keys must stay server-side. Browser-exposed keys are effectively public and should be treated as compromised.
Reusing one key for all environments
Environment-specific keys reduce blast radius and make incident response much faster.
Important