Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Modellen Tools & Services
Oplossingen
Organisaties Ontwikkelaars Internet Service Providers Managed Service Providers AI-in-a-Box
Kenniscentrum
Ondersteuning Documentation Blog Downloads
Bedrijf
Over ons Onderzoek Vacatures Investeren Contact
Inloggen

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.

bash
1
2
curl -H "Authorization: Bearer $TOKEN" \
     https://scaivault.scailabs.ai/v1/auth/whoami

Response:

json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "identity_id": "user:alice@acme.example",
  "identity_type": "user",
  "display_name": "Alice Smith",
  "tenant_id": "tnt_acme_prod",
  "partner_id": "ptn_acme",
  "scopes": ["secrets:read", "secrets:write", "audit:read"],
  "groups": ["group:sre", "group:oncall"],
  "roles": ["tenant_admin"],
  "mfa_verified_at": "2026-04-23T13:45:00Z",
  "token_expires_at": "2026-04-23T14:45:00Z"
}

Required: authenticated.

POST /v1/auth/introspect#

Validate a token without using it. Common in gateway/proxy scenarios.

bash
1
2
3
4
curl -X POST https://scaivault.scailabs.ai/v1/auth/introspect \
  -H "Authorization: Bearer $SELF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token": "token-to-introspect"}'

Response:

json
1
2
3
4
5
6
7
8
9
{
  "active": true,
  "identity_id": "sa:reporting-service",
  "identity_type": "service_account",
  "tenant_id": "tnt_acme_prod",
  "scopes": ["secrets:read"],
  "expires_at": "2026-04-23T15:00:00Z",
  "issued_at": "2026-04-23T14:00:00Z"
}

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.

bash
1
2
3
4
5
6
7
8
9
curl -X POST https://scaivault.scailabs.ai/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "token_exchange",
    "subject_token": "<k8s service account JWT>",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "audience": "scaivault",
    "resource": "https://scaivault.scailabs.ai"
  }'

Response:

json
1
2
3
4
5
6
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "secrets:read"
}

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}):

json
1
2
3
4
5
{
  "name": "release_signer",
  "scopes": ["sign:use", "sign:read"],
  "constraints": {"sign_path_prefixes": ["sign/acme"]}
}

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.

json
1
2
3
4
5
6
7
8
{
  "name": "release_signer",
  "scopes": ["sign:use", "sign:read"],
  "constraints": {
    "sign_path_prefixes": ["sign/acme"],
    "sign_path_excludes": ["sign/acme/root"]
  }
}

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.

http
1
2
3
4
PATCH /v1/service-accounts/{id}
{
  "allowed_source_ranges": ["203.0.113.10/32", "2001:db8:10::/48"]
}
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.

Updated 2026-11-12 21:59:42 View source (.md) rev 8