Authentication & API keys

Every /v1 request is authenticated with an API key. Keys are tied to your account and carry your tier, which governs your quota and which data you can read.

Getting a key

Sign up at noms.sh, verify your email, then mint a key from your dashboard: Dashboard → API Keys → Create key. The raw key is shown once at creation and never stored, so copy it somewhere safe. If you lose it, revoke it from the same screen and mint a new one.

If a key may have leaked, rotate it in place: Dashboard → API Keys → Rotate. Rotation keeps the key's label, tier and usage history, reveals a fresh secret once, and invalidates the old secret immediately. Update your integrations with the new value; the old one stops working the moment you rotate.

Your plan belongs to your account, not to a key

New accounts start on the Taster plan. Your plan sets your quota and what data you can read, and every key on the account is on it, including keys you minted long before. Upgrade or downgrade under Dashboard → Billing and all of your keys move together, immediately; there is no such thing as an old key stuck on an old plan, or a new key that carries more allowance than the rest. Track per-key consumption under Dashboard → Usage.

A key looks like noms_sk_live_.... Treat it like a password: never commit it, never ship it in client-side code, and rotate it if it leaks.

Sending your key

Send your key in the X-API-Key header on every request:

curl https://api.noms.sh/v1/foods?q=oats \
  -H "X-API-Key: $NOMS_KEY"

Bearer also works

For clients that prefer it, Authorization: Bearer <key> is accepted and behaves identically to X-API-Key. The interactive examples elsewhere in this guide use the Bearer form. Either is fine.

When auth fails

A missing, malformed, revoked, expired or unknown key returns a deliberately opaque 401. We never reveal why a key failed, to avoid leaking a key-probing signal:

401 Unauthorized

{
  "type": "/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Valid authentication is required to access this resource.",
  "doc_url": "https://api.noms.sh/docs#tag/unauthorized"
}

Next steps

Querying & data model: the four levers for reading data, and the envelope it comes back in.
Rate limits & quotas: what each plan allows, and how to read your standing.