Authentication and keys

Every call to /v1/systemone, /v1/decisions and /v1/models needs an API key in the Authorization header:

Authorization: Bearer sieve_app_live_...

Key formatCopy Anchor Link

Keys start with sieve_app_live_, then 40 random letters and digits, an underscore and a 6-character checksum. The checksum lets us reject a mistyped key without a lookup. Keys are never stored in the clear: we keep a keyed hash (HMAC-SHA-256 with a server-side secret), so a database leak does not reveal your keys.

Create and manage keysCopy Anchor Link

API keys belong to your organisation. Create them in the console under API keys.

• The full key is shown once, when you create it. Copy it then. We cannot show it again; create a new key if you lose it.
• When you create a key you choose:
  • a name, so you can recognise it later;
  • who owns it: a personal key belongs to you and is revoked automatically if you are removed from the organisation; a service account key belongs to the organisation, is meant for servers and CI, and keeps working when people leave (admins only);
  • what it can do: Full access (every API call: decisions, models and assurance; the default), Read only (list models), or Custom (pick "Make decisions" for /v1/systemone and /v1/decisions, "List models" for /v1/models, "Read assurance" (assurance:read) for /v1/assurance/report and /v1/assurance/verify, and "Report outcomes" (assurance:write) for /v1/assurance/outcomes);
  • an expiry: 7, 30, 60, 90 (the default), 180 or 365 days, a custom date, or never. If an admin sets a maximum key lifetime in Organisation settings, longer choices and "Never" are not offered.
• Under Restrictions (optional) you can also set:
  • Models: pick from sieve-auto, sieve-latest, sieve-0.8b, sieve-2b, sieve-4b, sieve-9b, sieve-27b, sieve-31b and sieve-preview. None picked means all models. A public name also allows the exact version it currently points to (for example sieve-9b allows sieve-9b-v2); sieve-auto counts as its own model. The model list from /v1/models shows only the models the key may use.
  • Allowed IP addresses: one IPv4 or IPv6 address or CIDR range per line, up to 50. Empty means any IP. Calls from other addresses get 403. The API checks the real client address, not the address of our load balancer.
• The keys table shows each key's last four characters, Access (Full access, Read only, Decisions only, or "Decisions + models" for keys created before assurance access was part of Full access, plus any assurance access, its models and IP ranges, or "all models · any IP"), Expires date and status.
• We email 7 days before a key expires, 1 day before, and when it has expired. The email goes to the key's creator; for service-account keys it goes to the organisation's admins. Short-lived keys skip the early reminders.
• Rotate creates a new secret with the same settings. The old key can stop at once or keep working for 1 hour or 24 hours while you switch.
• Budget (admins): give a key a monthly spending cap. See Monthly budgets below.
• Revoke stops a key within seconds. Admins can also Revoke all keys in Organisation settings, which stops every key in the organisation at once.
• An expired or revoked key gets a 401.
• Keep keys out of browsers and mobile apps. The JavaScript SDK refuses to run in a browser unless you set dangerouslyAllowBrowser.

Monthly budgetsCopy Anchor Link

Admins can cap what keys spend in a calendar month (UTC):

• Per key: in the keys table, choose Budget next to a key, enter an amount in your organisation's currency and save. The keys table shows each capped key's spend this month next to its budget.
• All keys together: in Settings → Organisation → Monthly budget. This caps the total of every key in the organisation.

Both can be set at once; a call must fit under every cap that applies, and under your prepaid balance. A budget of 0 blocks every paid call. Spend counts settled calls from 00:00 UTC on the 1st and starts from zero again each month. A change applies within seconds. Remove budget takes the cap away.

A call that would take this month's spend over a budget gets 429 with type insufficient_quota and code key_budget_exceeded (the key's budget) or project_budget_exceeded (the organisation-wide budget), a message saying when the budget resets, and an X-Sieve-Budget-Resets-At header with that time. There is no retry-after: retrying does not help before the reset. Raise or remove the budget to continue sooner.

Admins get an in-app notice when a key or the organisation reaches 80% of its budget, and again at 100%.

Send the keyCopy Anchor Link

curl https://api.sieve.one/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

For /v1/decisions with the OpenAI SDK, use base_url="https://api.sieve.one/v1" and your Sieve key as api_key. See /v1/decisions.

When the key is wrongCopy Anchor Link

A missing or invalid key returns 401. We never answer 403 for a missing key. A valid key gets 403 when its organisation is suspended, when the key has an IP allowlist and the call comes from another address, when its access level doesn't cover the route (for example a Read only key making a decision), or when it isn't allowed the requested model.

{
  "detail": {
    "error_type": "authentication_error",
    "message": "Must supply an API key! Check your request and try again."
  }
}

{
  "detail": {
    "error_type": "authentication_error",
    "message": "Cannot authenticate with the server. Please check your API key and try again."
  }
}

The first body is for a missing or blank Authorization header. The second is for every other failure: a header that is not Bearer <key>, or an unknown, malformed, expired or revoked key. See Errors for all codes.

API keys are scoped to an organisation. Use separate keys for separate applications. Assurance access requires explicit assurance:read or assurance:write permissions. Rotating an expired or revoked key is refused; create a new key instead.

Next stepsCopy Anchor Link