Authentication & API keys

Every authenticated Stav endpoint takes a Bearer token in the Authorization header. Tokens look like hm_live_<random> for production keys.

Creating your first key

1. Sign in to the Customer Portal.
2. Open Connect → Keys from the left navigation.
3. Click Create new key.
4. Give the key a descriptive name (prod backend, staging tests, roland-laptop). Future-you will thank present-you.
5. Pick the scopes the key needs. Default to least privilege — if the key only calls chat completions, give it only inference:chat.
6. Optionally set an IP allowlist and an expiry date.
7. Click Create.

Important: the secret value (hm_live_...) is shown once, at creation time. Copy it into your password manager or secrets store immediately. You cannot retrieve it later — only rotate the key for a new value.

Scopes

Scopes restrict what an individual key can do. Each scope below corresponds to one inference contract:

• inference:chat — /v1/chat/completions (OpenAI-compatible)
• inference:messages — /v1/messages (Anthropic-compatible)
• inference:embeddings —

A key with no scopes can still hit the anonymous /v1/public/* catalogue endpoints but nothing else.

Best practice: one key per workload, with only the scopes that workload needs. A leaked inference:chat-only key cannot exfiltrate embeddings or be used to call other workloads' models.

Using the key

In every request, send:

Authorization: Bearer hm_live_...

Most SDKs read the key from an environment variable. Common variable names:

• STAV_API_KEY — Stav's recommended convention.
• OPENAI_API_KEY — works with the OpenAI SDK when you also set base_url.
• ANTHROPIC_API_KEY — works with the Anthropic SDK when you also set base_url.

The Stav API doesn't care which variable name you read from in your code — only the Authorization header on the wire matters.

Rotation

Rotate any key that may have been exposed (committed to a repo, pasted in chat, included in a screenshot, etc.). Rotation does two things:

1. Generates a new secret value. Same key ID, new hm_live_... token.
2. Optionally keeps the old value valid for a grace window. Default 24 hours, configurable per rotation. Use this to roll the new secret through your deploys without a sharp cutover.

To rotate:

1. Customer Portal → Connect → Keys.
2. Click the key.
3. Click Rotate, set the grace window, copy the new secret.
4. Update your deployment / secrets manager with the new secret.
5. Verify traffic is using the new secret. Check Connect → Keys → Usage for "last used" timestamps on the old and new versions.
6. After the grace window, the old secret stops working automatically.

We recommend rotating production keys at least every 90 days even if there's no incident. The rotation flow is designed to be a no-downtime operation.

If a key leaks

If you discover an exposed key:

1. Revoke immediately (Customer Portal → Connect → Keys → click key → Revoke). The key stops working within seconds. No grace window.
2. Create a new key with the same scopes and roll it into your deploys.
3. Audit the usage of the leaked key in Connect → Keys → Usage for the period it was exposed. Anything unexpected? Open a support ticket so we can correlate with platform-side logs.

You're never billed for usage on a revoked key after the revocation timestamp.

IP allowlist

You can scope a key to a list of source IPs (or CIDR blocks). Requests from outside the list return 401. Useful for keys that only ever call from one production datacenter; less useful for keys that run from end-user devices or serverless functions with rotating IPs.

The allowlist is set at key creation and editable later. Empty allowlist = any IP allowed (the default).

Team keys vs user keys

Two key flavours exist. Most customers use only the first.

• Team keys — provisioned by team admins, billed against the team plan, scoped to one team. The flow above creates a team key.
• User keys — per-seat keys provisioned to individual team members under a team's user-key policy. Used when individual usage needs to be billed back or limited separately. Self-service for team members where enabled; otherwise admin-approved. See Connect → Team → User keys for the team's policy.

Programmatic key management

Programmatic CRUD on keys (via the API rather than the portal UI) is on the roadmap as a Phase 2b deliverable. For now, all key management happens in the Customer Portal.

Next steps

• Sovereignty — understand what running on Stav guarantees about your data.
• Full API reference — the bearer-auth scheme is documented at the top of every operation.