Authentication
Vanguard AI has three credential types. Programmatic calls should always use an API key.
| Credential | Header | Used by |
|---|---|---|
| API key | Authorization: Bearer nt_live_... | Server‑to‑server CV/AI calls |
| JWT (session) | Authorization: Bearer <jwt> | Dashboard / self‑serve actions, including managing keys |
| Admin key | X-Admin-Key: <key> | Back office only (not covered here) |
- A JWT identifies a user within an organization — use it for dashboard actions such as minting keys or reading your balance.
- An API key identifies an organization and is what you ship in your servers to call the OCR, STT, TTS, Images, Chat, Agents, Responses and Embeddings endpoints.
Sending your key
curl https://ai-api.vanguardinitiative.com/v1/services \
-H "authorization: Bearer nt_live_your_key_here"Key format
API keys look like nt_live_ followed by 43 characters. They are stored only as a
SHA‑256 hash; the plaintext is returned once when the key is created.
Managing keys
Keys are created, listed and edited from a dashboard session, never with an API
key. POST, GET and PATCH /v1/auth/keys refuse an API key with 403 KEY_MANAGEMENT_REQUIRES_SESSION. Without that rule a key scoped to OCR alone could
mint itself a second key with every scope, or widen its own list, and a scope would
limit nothing.
The one thing a key may do to keys is revoke itself. An integration that suspects its key has leaked can switch it off at once, without waiting for someone to sign in:
curl -X DELETE https://ai-api.vanguardinitiative.com/v1/auth/keys/$KEY_ID \
-H "authorization: Bearer $API_KEY"$KEY_ID is the id returned when the key was created. The answer is { "status": "success", "revoked": "<id>" }, and from then on the key gets 401.
Revoking any other key with an API key is refused with the same 403, so one leaked
key cannot take down the rest of your integrations.
Scopes
Each key carries scopes that decide what it can call. A call outside them returns 403 SCOPE_FORBIDDEN. Grant each key only what its integration needs; you can change a
key’s scopes on the API keys page at any time, without issuing a new one.
| Scope | Lets the key call |
|---|---|
ocr, stt, tts, docproc | That service’s /v1/{service}/scan and /v1/{service}/jobs |
chat | Everything under /v1/chat — see Chat |
agents | Everything under /v1/agents — see Agents |
responses | POST /v1/responses — see Responses |
embeddings | POST /v1/embeddings — see Embeddings |
images | Everything under /v1/images — see Images |
The full list is the scope of each entry in GET /v1/services. A
dashboard session holds every scope. GET /v1/services and GET /v1/chat/models are
public and need no key at all.
Rate limits & credits
Every call is also checked against your plan’s per‑minute rate limit and your credit balance. See Errors & conventions for the 429 and 402 responses and the headers to watch.