67 docs indexed

Identity Tokens

Accept short-lived JWT access tokens from your identity provider on the data plane, alongside API keys, with zero per-user setup.

The data plane accepts two kinds of bearer credential on Authorization: Bearer:

  • an API key (sk_…), minted from the dashboard or Management API, and
  • an identity token: a short-lived JWT access token minted by an OIDC identity provider you trust.

A token is verified offline against the issuer's published signing keys (JWKS). A verified (issuer, subject) pair maps to an identity key — a real key row of kind identity under a tenant you name — created on first use. From that point the request is handled exactly like one made with an API key: tenant status, schedules, budgets, model allowlists, guardrails, and disable all apply.

Configure an issuer

Set OBLETH_JWT_ISSUERS on the gateway to a JSON array. One entry per trusted issuer:

[
  {
    "issuer": "https://idp.example.com",
    "jwks_url": "https://idp.example.com/.well-known/jwks.json",
    "audience": "obleth",
    "algorithms": ["ES256"],
    "subject_claim": "sub",
    "device_claim": "device_id",
    "identity_claims": ["uid"],
    "tenant": "cli-users",
    "jit_provision": true
  }
]
FieldRequiredDefaultMeaning
issueryes—Must equal the token's iss exactly.
jwks_urlnodiscoverySigning-key document. When omitted, jwks_uri is read from <issuer>/.well-known/openid-configuration at boot.
audienceyes—Must appear in the token's aud.
algorithmsno["RS256","ES256"]Allowed signature algorithms. Asymmetric only; HS* is refused at boot.
subject_claimnosubClaim that identifies the user.
device_claimno—Claim recorded as device_id on usage rows (letters, digits, _, -; at most 64 characters).
identity_claimsno[]Extra claims stored on the identity key at creation, e.g. an immutable user id.
tenantyes—Tenant that identity keys are created under. Must match the tenant your account system already uses.
jit_provisionnotrueCreate the identity key on first sight. When false, unknown identities receive 401.

An invalid configuration stops the gateway from starting. The JWKS URL is subject to the same destination policy as any upstream address.

Verification

  • exp, nbf, and iat are checked with 60 seconds of clock skew.
  • iss and aud must match the issuer entry.
  • Signing keys are cached and refreshed every 15 minutes. If a refresh fails, the previous keys keep verifying; only new logins depend on the issuer being reachable. An unknown key id triggers one immediate refresh per minute.
  • Every failure returns 401 with invalid token. The reason is exported as obleth_jwt_verify_total{result}.

Identity keys

Identity keys appear on the Keys pages with an identity badge, the subject, and the issuer host. They have no secret, so there is nothing to copy or rotate. Disabling one blocks that user's token traffic immediately, ahead of the token's own expiry. Deleting one removes it; the next verified token recreates it with fresh budgets. Disable, not delete, is the revocation control for identity keys.

The Management API returns kind, identity_issuer, identity_subject, and identity_claims on each key. identity_subject is the field external account systems should join on.

Tenant mismatch

If the tenant named for an issuer does not exist, it is created with default policy and an alert is raised. In a deployment where your account system already manages that tenant, treat the alert as a configuration error: token traffic has landed in a new tenant instead of the intended one.

Usage

The request log and GET /api/v1/usage/logs include device_id for identity-key traffic, and accept device_id as a filter.