API tokens and SCIM

For unattended access — CI jobs, export scripts, identity provisioning — use an API token rather than a user JWT. Tokens are created by org admins, are scoped to a set of capabilities, and belong to the organization rather than to a person, so they survive staff changes.

Scoped API tokens

An org admin mints a token in the admin console and chooses its scopes. The token is shown once at creation and stored only as a hash; treat it like any other secret. Use it exactly like a bearer JWT:

curl -H "Authorization: Bearer $API_TOKEN" \
  https://your-host.example.com/api/events/v1?from=2026-06-01

Token lifecycle events are themselves audited (API_TOKEN_CREATED, API_TOKEN_REVOKED), so the creation and revocation of programmatic access is on the same tamper-evident trail as everything else. Revoke a token at any time and in-flight callers stop immediately.

Tenant context is established server-side

This is the part that matters for isolation. Token-authenticated routes do not trust the caller to scope their own queries. The server resolves the token to its organization and runs the request inside that org’s context (via runWithOrg) before any query executes. Row-level security is then enforced in the database for the whole request — a token can only ever see its own org’s rows, even on the SCIM and Events routes that are reached without an interactive login.

SCIM 2.0 provisioning

VaultTerm implements SCIM 2.0 at /scim/v2 for automated identity lifecycle. Point your IdP’s SCIM connector at that base URL and authenticate it with an API token that carries the scim scope. The connector can then:

• Provision and deprovision users as they are added to or removed from the app in your IdP.
• Map IdP groups to VaultTerm teams, so group membership in Okta, Azure AD, or OneLogin keeps team membership in sync automatically.

SCIM activity is audited as SCIM_USER_PROVISIONED, SCIM_USER_DEPROVISIONED, SCIM_GROUP_PROVISIONED, and SCIM_GROUP_DEPROVISIONED.

SCIM provisioning is an Enterprise capability and pairs with enterprise SSO — see SSO and SCIM for configuring the identity provider side.

Notes

• A token is org-scoped: it cannot act across organizations regardless of its scopes.
• Use the narrowest scope set that the integration needs; the scim scope should go only on a token dedicated to the IdP connector.
• Rotate tokens on a schedule and revoke any token whose consuming system is decommissioned.