AI GridDocs
Sign Up

Authentication

Bearer keys, each bound to exactly one project.

Updated Sep 9, 2026

Authenticate with a bearer token:

bash
curl https://api.aigridapp.com/v1/models \
  -H "Authorization: Bearer $AIGRID_API_KEY"

One key, one project#

A key looks like aig_ followed by a random token. It is created in the console (API keys) and is bound to exactly one project at creation — the request must name the project (422 project_required if omitted), and the binding never changes. That project is the execution and charging context of every call the key makes: usage, spending limits and the project wallet all attach to it.

You see the secret once, at creation. Only its SHA-256 hash is stored, and every later view shows the key's prefix, never the secret. A lost secret means revoking and creating again.

Who may issue a key. You need an active membership of the organization, an active grant on the project's owning team (Team Owner or Team Member), and an active project grant that carries invocation rights (Project Owner or Project Consumer). Organization administration alone does not qualify (403 key_issuer_denied). The rule is re-checked on every use of the key — revoke the creator's grant and the next call is refused.

No project picking per call#

Because the key names its project, calls need no selector. The selector headers X-AIGrid-Project (and its aliases X-Project-ID and the body field project_id) survive only as a consistency check: they may restate the bound project, and a value that differs is refused before any money is reserved:

bash
curl https://api.aigridapp.com/v1/chat/completions \
  -H "Authorization: Bearer $AIGRID_API_KEY" \
  -H "X-AIGrid-Project: <the same project the key is bound to>" \
  -d '{"model": "openai/gpt-oss-20b", "messages": [{"role": "user", "content": "Hello"}]}'
Situation Result
Selector omitted, or restates the bound project call proceeds
Selector names a different project 403 project_mismatch
Key predates project binding (legacy, unbound) 403 key_unbound everywhere

Legacy unbound keys are never auto-bound or auto-revoked, and cannot be rotated — the console shows them as "Needs reissue". Create a project key and revoke the old one.

Limiting what a key can do#

At creation you can narrow a key, and only narrow it:

  • Access policy — all-eligible (the default: every resource the project can reach, including ones added later) or listed (an explicit allowlist; each id must be an eligible resource of the project, else 422 resource_not_eligible). A resource outside the list is refused with 403 key_scope.
  • Spending limit — an optional micro-USD ceiling with a reset of daily, weekly, monthly or lifetime. Reaching it refuses calls with 403 key_limit until the window resets. See Rate limits.
  • Expiry — 1–365 days, default 90.

Rotation#

Rotate from the console or POST /api/v2/tenants/{tenantID}/keys/{keyID}/rotate. Rotation issues a replacement secret with the same project, access policy, allowlist, spending limit and expiry span, and records the lineage (rotatedFrom / rotatedTo).

Next#