Authentication
Token exchange, introspection, and identity lookup. For conceptual overview see Authentication.
ScaiVault delegates identity to ScaiKey. Most auth endpoints live on ScaiKey; ScaiVault exposes a thin layer for token introspection and context discovery.
Base path: /v1/auth/
GET /v1/auth/whoami#
Identify the caller from the bearer token. Useful for debugging — shows you who ScaiVault sees you as.
1 2 | |
Response:
1 2 3 4 5 6 7 8 9 10 11 12 | |
Required: authenticated.
POST /v1/auth/introspect#
Validate a token without using it. Common in gateway/proxy scenarios.
1 2 3 4 | |
Response:
1 2 3 4 5 6 7 8 9 | |
If the token is invalid or expired: {"active": false} with HTTP 200.
Required: admin scope.
POST /v1/auth/exchange#
Exchange a foreign token (workload identity from Kubernetes, AWS, GCP, etc.) for a ScaiKey-minted ScaiVault token. Used by services that don't have static credentials.
1 2 3 4 5 6 7 8 9 | |
Response:
1 2 3 4 5 6 | |
Configure the trust relationship (which foreign issuers to accept, how to map to ScaiKey identities) in the admin UI under Access → Token Exchange.
Required: none (the subject token authenticates).
Credentials: bearer tokens and API keys#
ScaiVault accepts two credential types, and they go in different headers:
| Credential | Header | Used by |
|---|---|---|
| ScaiKey JWT | Authorization: Bearer <jwt> |
human sessions, OAuth clients |
ScaiVault API key (key_…) |
X-API-Key: key_… |
service accounts, the CLI, the certificate agent |
An API key sent as a bearer token is rejected — the server tries to parse it as a JWT and fails with Not enough segments. All three SDKs detect a key_ prefix and route it to the correct header automatically, so passing either as token works.
Scopes#
Scopes constrain service accounts. Human users authenticated through the admin UI bypass scope checks, on the basis that the UI login is itself the control — so adding a scope to an endpoint restricts machine callers, not people. Where that is too weak, an endpoint carries an explicit role check as well (certificate private-key export is the current example).
| Category | Scopes |
|---|---|
| Secrets | secrets:read secrets:write secrets:delete secrets:list |
| PKI | pki:read pki:write pki:delete pki:export-key |
| Signing | sign:create sign:use sign:read sign:manage sign:destroy |
| ACME | acme:read acme:write acme:delete |
| DNS | dns:read dns:write dns:delete |
| Dynamic secrets | dynamic:read dynamic:write |
| Rotation | rotation:read rotation:write |
| Policies | policies:read policies:write policies:delete |
| Secret policies | secret_policies:read secret_policies:write |
| Webhooks | webhooks:read webhooks:write |
| Subscriptions | subscriptions:read subscriptions:write |
| Service accounts | service_accounts:read service_accounts:write service_accounts:delete |
| Identity | identity:read identity:* |
| Roles | roles:read roles:write roles:delete |
| Audit | audit:read |
| Operations | admin:read |
Wildcards work per namespace: secrets:* grants every secrets: scope, and * grants everything. A namespace wildcard does not cross namespaces — secrets:* grants no PKI access.
pki:export-key is separate from pki:write on purpose. Exporting a stored private key takes the key material outside ScaiVault's boundary, so it needs its own grant, is audited on every call, and additionally requires an administrator role for human callers.
Resource constraints#
A role can narrow its scopes to specific resources with constraints. Once any of a credential's roles declares a list for a dimension, every request in that dimension must fall inside the union of those lists; a role that declares nothing adds nothing. A credential with no constraints is limited only by its scopes.
| Constraint | Narrows | Example |
|---|---|---|
sign_path_prefixes |
Signing keys the credential may create, list, use or manage | ["sign/acme"] |
sign_path_excludes |
Signing keys the credential may never touch, even inside its prefixes | ["sign/acme/root"] |
pki_path_prefixes |
Certificate paths it may read, issue, sign or import | ["pki/acme/web"] |
acme_dns_suffixes |
DNS names it may order ACME certificates for | ["web.example.com"] |
Path prefixes match per segment: sign/acme covers sign/acme/release-manifest but not sign/acmex. A DNS suffix matches the name itself and its subdomains. Set constraints when you create or update a role (POST /api/v1/roles, PATCH /api/v1/roles/{id}):
1 2 3 4 5 | |
sign_path_excludes works the other way round: a key at or under an excluded path is refused for every signing operation and hidden from the key list. Exclusions from all of a credential's roles are combined, and an exclusion always wins over a prefix, including a prefix from another role. On its own, an exclusion leaves everything else open, including keys created later; to keep future keys closed by default, list what is allowed in sign_path_prefixes instead.
1 2 3 4 5 6 7 8 | |
A request outside the allowed resources returns 403 access_denied.
Source-address restriction#
A service account can be limited to the network addresses it calls from. Set allowed_source_ranges to a list of IPv4 and IPv6 addresses or CIDR prefixes. Every call made with any of the account's API keys must then come from one of them, signing calls included. A call from anywhere else gets 403 source_address_not_allowed before the request is processed, and the refusal is written to the audit log with the address it came from.
1 2 3 4 | |
| Value | Effect |
|---|---|
omitted (on PATCH) |
unchanged |
null or [] |
any address (the default) |
| list of prefixes | only those; a bare address means /32 or /128 |
Prefixes must not have host bits set (10.0.0.1/24 is rejected with 422), and an account takes at most 64. The restriction belongs to the account, so it covers every key the account has, including keys created later. It works alongside scopes, resource constraints and secret policies; it never widens them. The admin console's service-account form has a field for it, and the account list marks restricted accounts.
The address checked is the one ScaiVault's own front end received the connection from. X-Forwarded-For and X-Real-IP headers sent by the caller are ignored. If your calls leave through NAT, list the translated address, and keep in mind that it allows every host behind the same NAT.
OAuth flows on ScaiKey#
Everything else — authorization code + PKCE, client credentials, refresh token rotation — happens on ScaiKey directly. See scaikey.scailabs.ai/docs. ScaiVault accepts the resulting bearer tokens on every endpoint.
Related#
- Authentication (Getting Started)
- Multi-tenancy
- Identity Reference
- Enrollment — how a new host obtains its own credential