Guides

Authentication

How API keys work, how to scope them, and how to rotate one without downtime.

Every request carries a bearer token in the Authorization header. There is no other authentication scheme.

bash
curl https://api.trystac.com/v1/chat/completions \
  -H "Authorization: Bearer $STAC_API_KEY"

A missing, malformed, invalid, or expired key all return 401. There's no 403 case — a key is created scoped to one stack, so there's no "valid key, wrong stack" state to report.

Key scope

A key belongs to exactly one stack. It cannot read another stack's knowledge base, cannot change behavior, and cannot reach the dashboard API. The blast radius of a leaked key is one stack.

Expiry

Keys can expire. Pick a window at creation:

expires_atstring | nullOptionalDefault: null

ISO 8601 timestamp, or null for a key that never expires. Requests with an expired key return 401.

today7d30d90dcustomnone
namestringRequired

Label shown in the dashboard. Use the consumer's name — checkout-service, not key 3 — so revocation later is unambiguous.

Short-lived keys are the right default for CI and for anything running on a machine you do not control.

Rotating without downtime

  1. Create the replacement

    A stack accepts multiple active keys, so the new one works before the old one is gone.

  2. Deploy it

    Update the secret and roll your service. Both keys are valid during the rollout.

  3. Confirm the old key is idle

    The Usage page shows last-used per key. Wait until the old key has been quiet for a full deploy cycle.

  4. Revoke

    Revocation is immediate — in-flight requests complete, new ones get 401.

Handling failures

StatusCause
401No Authorization header, an unrecognized key, or a key past its expires_at

The response body is { "detail": "..." } — see Errors for the full error shape. A 401 is never retryable: treat it as a configuration problem, not a transient error — retrying with the same key fails identically.