Authentication

The public API lives under /v2 and accepts exactly one credential: a gat_ API key sent as an HTTP bearer token.

curl https://api.graine.ai/v2/user/me \
  -H "Authorization: Bearer gat_YOUR_KEY_HERE"

There is no second way in: no other header, no ?api_key= query parameter, and no browser session token. One documented path means a partner integration cannot half-work — it either authenticates or it fails loudly.

The bearer scheme

The scheme and the credential are split on the first run of whitespace, so Authorization: Bearer gat_abc and Authorization: bearer gat_abc are both accepted. Anything that is not two whitespace-separated parts — a bare Authorization: gat_abc with no scheme, or Authorization: Basic ... — is treated as no credential at all and returns 1100, not 1101.

Key format

Keys always start with the literal prefix gat_, followed by a URL-safe random string minted from 32 bytes of entropy:

gat_1oJ9Zt7Yq2Kx4RbW8sNfHc0LdPmV3gTuA6iE5nQzYwU

The prefix is what makes an immediate rejection possible. Because the API can tell from the first four characters whether a credential could ever be a valid API key, a non-gat_ bearer is refused before anything else is checked.

Session tokens are rejected

The dashboard signs people in with browser session tokens. Those are for the dashboard only: on /v2 they are refused outright with a dedicated error code:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": 1101,
  "message": "A browser session token is not a public API key. Authenticate with Authorization: Bearer gat_..."
}

Two reasons this is its own code rather than a generic 1100:

• A leaked dashboard session must never drive the public API. The two credentials have different blast radii and different revocation stories.
• A session carries no plan or rate-limit tier, so it cannot be metered the way a key is.

The check is a prefix comparison on the credential itself, so a session token is refused immediately, before any key is looked up.

Rejection order

A key is checked in this exact order, stopping at the first failure. Knowing the order tells you what a given code rules out:

Step 2 is decided from the credential alone. Steps 3 and 4 look the key up. Step 5 is a hard 403 rather than a permissive fallthrough: a key with no organization must never be able to read across organizations.

Every auth failure response

All /v2 errors use one flat envelope — no nesting, no detail key, no validation array. The HTTP status is derived from the integer code, so the two can never drift apart.

{
  "error": 1100,
  "message": "Invalid API key. A key looks like 'gat_' followed by 43 characters; check yours was copied in full."
}

These are the codes an authenticated request can hit before your handler runs:

The full response bodies:

{ "error": 1100, "message": "Missing bearer token. Send Authorization: Bearer gat_..." }

{ "error": 1100, "message": "Invalid API key. A key looks like 'gat_' followed by 43 characters; check yours was copied in full." }

{ "error": 1100, "message": "API key is inactive." }

{ "error": 1101, "message": "A browser session token is not a public API key. Authenticate with Authorization: Bearer gat_..." }

{ "error": 1102, "message": "This API key is not bound to an organization." }

{ "error": 1102, "message": "This API key is not authorized for that organization." }

{ "error": 1102, "message": "This API key is not authorized for this action. Missing scope: keys:write." }

{ "error": 1501, "message": "API key checks are temporarily unavailable." }

Organization scoping

An API key is bound to exactly one organization at mint time, and that binding is the whole tenancy boundary. Every /v2 route resolves the organization from the key — never from the request.

For compatibility, routes accept an organization_id query parameter. It is validated, not honoured: any value other than the key's own organization is a hard 1102/403. It is never a silent override.

# Redundant but harmless — this is the key's own org.
curl "https://api.graine.ai/v2/api-keys?organization_id=org_your_own" \
  -H "Authorization: Bearer gat_YOUR_KEY_HERE"
 
# 403, error 1102 — not your organization.
curl "https://api.graine.ai/v2/api-keys?organization_id=org_someone_else" \
  -H "Authorization: Bearer gat_YOUR_KEY_HERE"

Scopes

/v2 defines eleven scopes. GET /v2/scopes returns this table, the routes each one gates, and whether the calling key holds it — call it first whenever a 403 surprises you.

Absent is not empty

This is the one rule to take away, and it is the difference between two values that are both falsy in most languages:

Every key minted before scopes existed carries no scopes field, and is therefore unrestricted — deliberately. Reinterpreting an absent policy as "deny" would have broken every integration built against this API so far. Every key minted since carries an explicit list, so the grandfather clause does not propagate.

keys:write is the exception in both directions: it is never implied by a grandfathered key, and it must be granted deliberately with grant_api_keys_write: true. It is the scope that can extend every other one.

What is enforced today

Every route you call with a key checks a scope, reads included, with two exceptions below. A key that holds an explicit list without the named scope gets 1102/403, and the denial is itself recorded in the audit trail:

The two exceptions need only a valid key: GET /v2/user/me, because a key may always describe itself, and GET /v2/scopes, because a key must always be able to find out why it was refused.

Minting a narrower key

POST /v2/api-keys takes an optional scopes array:

# A key that can dial and read its own calls, and nothing else.
curl -X POST https://api.graine.ai/v2/api-keys \
  -H "Authorization: Bearer gat_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "name": "dialer-prod", "scopes": ["calls:read", "calls:write"] }'

• Omit scopes and the new key inherits everything the minting key effectively holds, minus keys:write. A grandfathered minter writes the full taxonomy out explicitly rather than passing its own absence on.
• Send [] and you mint a key that can do nothing. That is allowed, and it means what it says.
• You can never grant a scope you do not hold. Asking for one is a 1102/403 naming the scopes — not a silently trimmed list, because a caller who believes it minted a broader key will ship an integration built on it.
• keys:write in scopes is dropped, without an error. The new key is minted without it. The only way to give a new key keys:write is grant_api_keys_write: true.
• An unknown scope string is a 1001/422 listing the valid values.

The 403

A scope denial from a gated route:

{
  "error": 1102,
  "message": "This API key is not authorized for this action. Missing scope: agents:write."
}

Minting or revoking without keys:write is the same refusal, naming keys:write. It is 1102, the same code as a cross-organization attempt. Branch on the code and read message for the reason; never parse the message.

Keys and workspace roles

A key can never do through the API what the person who made it cannot do in the dashboard. Every workspace member is an Admin, a Member or View only (Team roles), and a key carries its creator's limits with it.

The member scopes:

agents:read   agents:write   calls:read   calls:write
batches:write  webhooks:read  account:read

A Member's key never holds keys:write, so it cannot create or revoke keys. Where an action is admin-only in the dashboard — deleting or archiving an agent, deleting a campaign — the API refuses it for a Member's key with a 403, even though the key holds agents:write or batches:write.

In the dashboard, a Member's API keys page lists only the keys they created; an Admin's lists every key in the workspace with who created it, and keys a Member made are marked as such.

Identifying a key

You never address a key by its secret. Two derived values do that job:

key_id       key_9f2a4c1b8e7d3506
key_preview  gat_1oJ9Zt7Y...zYwU

key_id is stable and non-reversible: it identifies a key permanently without ever exposing anything that could be replayed as a credential. A key of 16 characters or fewer is returned as-is in key_preview rather than masked.

To find the key_id of the key you are currently holding, call GET /v2/user/me and read developer.key_id:

curl https://api.graine.ai/v2/user/me \
  -H "Authorization: Bearer gat_YOUR_KEY_HERE"

{
  "organization_id": "org_live_9312",
  "developer": {
    "id": "dev_4c1b8e7d3506af92",
    "name": "Billing integration",
    "key_id": "key_9f2a4c1b8e7d3506",
    "key_preview": "gat_1oJ9Zt7Y...zYwU"
  },
  "plan": "pro",
  "rate_limit_tier": "pro"
}

List keys

GET /v2/api-keys

Returns this organization's keys, newest first. Secrets are never included.

Query parameters

Scope required: keys:read.

curl "https://api.graine.ai/v2/api-keys?page=1&page_size=20" \
  -H "Authorization: Bearer gat_YOUR_KEY_HERE"

{
  "data": [
    {
      "key_id": "key_9f2a4c1b8e7d3506",
      "key_preview": "gat_1oJ9Zt7Y...zYwU",
      "developer_id": "dev_4c1b8e7d3506af92",
      "developer_name": "Billing integration",
      "developer_email": "ops@example.com",
      "plan": "pro",
      "rate_limit_tier": "pro",
      "token_type": "partner_api",
      "status": "active",
      "description": "Nightly reconciliation job",
      "created_at": "2026-08-14T09:12:44.518Z",
      "is_current": true,
      "scopes": ["agents:read", "calls:read", "calls:write"],
      "scopes_source": "explicit"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}

status is "active" or "inactive". An inactive key is refused at authentication with 1100. is_current is true for the key making the request — the one you must not revoke while you are using it.

scopes is the key's own list, and scopes_source is "explicit". A key minted before scopes existed has scopes null and scopes_source "grandfathered": it holds every scope except keys:write. An empty list is different — a key that holds nothing.

Rows are sorted newest first with a total, stable tie-break, so paging never shuffles a row between pages.

Errors: 1100, 1102 (missing keys:read, or wrong organization), 1300, 1501 (keys could not be read at that moment — message: API keys are temporarily unavailable.).

Mint a key

POST /v2/api-keys

Returns 201 Created. This is the only response in the entire API that ever carries a full secret, and it is shown exactly once.

Scope required: keys:write.

Body

Unknown fields are rejected, not ignored — a typo'd field name is a loud 1001/422 rather than a silently dropped setting.

curl -X POST https://api.graine.ai/v2/api-keys \
  -H "Authorization: Bearer gat_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing integration",
    "email": "ops@example.com",
    "description": "Nightly reconciliation job",
    "plan": "pro",
    "grant_api_keys_write": false
  }'

{
  "key_id": "key_c73e1a90f4d28b65",
  "api_key": "gat_1oJ9Zt7Yq2Kx4RbW8sNfHc0LdPmV3gTuA6iE5nQzYwU",
  "key_preview": "gat_1oJ9Zt7Y...zYwU",
  "developer_id": "dev_4c1b8e7d3506af92",
  "developer_name": "Billing integration",
  "plan": "pro",
  "rate_limit_tier": "pro",
  "org_id": "org_live_9312",
  "created_at": "2026-08-26T10:15:30.123Z",
  "message": "Save this key now - it will not be shown again."
}

What the new key inherits

• Organization. Always the minting key's own. It cannot be redirected.
• Scopes. The ones you sent in scopes, or without it everything the minting key holds. keys:write only with grant_api_keys_write: true.
• Plan. The minting key's plan, or a lower one — never higher.
• Rate-limit tier. Set equal to the resolved plan.

Plan ceiling

A key may mint another key on its own plan or a lower one. Requesting a higher plan is 1102/403. Plans are ranked:

A plan name that is not in this table can only be minted as an exact (case-insensitive) copy of the minting key's own plan. Anything else:

{
  "error": 1102,
  "message": "This API key cannot mint a key on the 'enterprise' plan. A new key may not exceed the minting key's plan ('pro')."
}

Limits and contention

An organization may hold 25 active keys. Revoked keys are deactivated rather than deleted and do not consume the cap, so rotation never permanently locks you out.

{
  "error": 1201,
  "message": "This organization already has 25 active API keys. Revoke one before minting another."
}

Key changes — mints and revokes — are applied one at a time, across all organizations, and each holds the others off for at most 10 seconds, so the change in progress may not be yours. A request that arrives meanwhile is refused rather than queued — retry it:

{
  "error": 1201,
  "message": "Another API key change is already in progress. Retry in a moment."
}

If key changes cannot be coordinated at that moment, the change is refused with 1501 (API keys are temporarily unavailable.) rather than risk losing a key.

Errors: 1000, 1100, 1102 (missing scope, wrong organization, a scope the minting key does not hold, or a plan above the minting key's), 1201 (a key change is in flight, or the active-key ceiling is reached), 1001, 1300, 1501.

Revoke a key

DELETE /v2/api-keys/{key_id}

Scope required: keys:write.

Path parameter

curl -X DELETE https://api.graine.ai/v2/api-keys/key_c73e1a90f4d28b65 \
  -H "Authorization: Bearer gat_YOUR_KEY_HERE"

{
  "key_id": "key_c73e1a90f4d28b65",
  "status": "inactive",
  "revoked": true,
  "revoked_at": "2026-08-26T10:41:02.774Z"
}

Four behaviours worth knowing:

• Revocation is deactivation, not erasure. status becomes inactive and authentication refuses the key from then on, but the record survives so an account admin can undo a mistake.
• You cannot revoke the key you are authenticating with. That check runs first, so an integration cannot lock itself out mid-run. It returns 1201/409: You cannot revoke the key you are authenticating with.
• Cross-tenant ids return 404, never 403. Only your own organization's keys can be selected, so a key id harvested elsewhere cannot reach another tenant's key — and the API never confirms that another tenant's key exists. Unknown id: {"error": 1200, "message": "API key not found."}
• Repeating the call is safe. Revoking an already-inactive key is a no-op that returns its original revoked_at rather than stamping a fresh one over the real timestamp.

Errors: 1002 (blank key_id), 1100, 1102 (missing scope or wrong organization), 1200 (no such key in this organization), 1201 (a key change is in flight, or you tried to revoke your own key), 1300, 1501.

Rotating a key

Rotation is mint-then-revoke, in that order, and it needs no downtime.

Handling keys well

Never put a key in a browser or a mobile binary. A /v2 key carries your whole organization. Call /v2 from your server; the dashboard's own session credential is deliberately rejected here precisely so the two never get confused.

Store keys in a secret manager, not in source. The only copy you will ever receive is the one in the mint response. Commit that to a repository and the only remedy is rotation.

Give each integration its own key. key_id, developer_name and description are all listed by GET /v2/api-keys, so per-integration keys make an incident a one-line revoke instead of a fleet-wide rotation. The 25-active-key ceiling is generous enough for that.

Keep the minting scope narrow. Leave grant_api_keys_write at false for anything that does not manage keys. A key that cannot mint keys cannot escalate.

Rate limits are per organization, not per key. Minting more keys does not buy more quota — the counter is keyed on the organization. Every response after your key is authenticated, errors included, carries the current state:

The ceilings are 2000 requests per minute on most routes; 1200 per minute — 1000 you can rely on sustained — on placing, stopping and transferring calls, creating campaigns, and reading calls; 20 on knowledge-base uploads; and 60 on transliteration. Exceeding one returns 1300/429 with Retry-After alongside the three headers above:

{
  "error": 1300,
  "message": "Rate limit exceeded: 2000 requests per minute for this organization. Retry in 42s."
}

Live figures for your own organization are on GET /v2/user/me under rate_limits (default_per_minute, calls_per_minute, executions_per_minute).

Retry 503, not 401. A 1501 is a temporary problem on our side and is worth retrying with backoff. A 1100, 1101 or 1102 is a decision about your credential and will return the same answer however many times you repeat it — fix the key instead.

Read the integer, not the sentence. Branch on error; messages are written for humans and may be reworded. message is always a single sentence and never contains a stack trace, another system's response body, a database query or a phone number.

Error code reference

Every /v2 code, so you can write one handler for the whole surface:

A 1001 names the offending field so you can fix it without guessing:

{
  "error": 1001,
  "message": "Invalid value for 'name': ensure this value has at most 100 characters."
}

All /v2 timestamps — created_at, revoked_at and every other — are ISO-8601 UTC with a literal Z and millisecond precision: 2026-08-26T10:15:30.123Z.