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

API keys

API keys are the agent-facing equivalent of a user session. Issue one, hand it to your agent or service, and the agent gains exactly the permissions of whatever the key is bound to — narrowed by optional scope qualifiers.

What a key is bound to#

A key is bound to either a user (acts as them) or a group (acts as the group, no user attribution). Exactly one; never both. Both routes funnel through the same RBAC engine — there is no parallel permission system for keys.

Scope qualifiers#

A key's scopes array can narrow what the key is allowed to do without changing the underlying role:

Scope Permits
(no scopes) Everything the bound principal has
docs:read Maps to docs.read permission
docs:write:scaigrid Write only within the scaigrid namespace
docs:write:scaigrid/v2/** Write only within version v2 (or a path prefix)
docs:* All docs.* perms
* Wildcard — same as no scopes

Scopes only narrow; they cannot grant a permission the principal doesn't already hold. This is enforced both for permissions globally (the docs:write part) and per-resource (the :scaigrid/... part — checked at write-time).

Auth header#

Same Authorization header as user JWTs; the backend disambiguates by the scai_ prefix.

bash
1
2
curl -H "Authorization: Bearer scai_live_xxxxxxxx…" \
     "$API/api/v1/docs/_namespaces"

Lifecycle#

  1. Issue in admin → /api-keys → New API key.
  2. The plaintext is shown once in a one-time modal. Copy it.
  3. The key is identified afterwards by its prefix (the first characters after scai_live_).
  4. Revoke by clicking Revoke — the key becomes is_active=false and subsequent requests get 401 Invalid API key.

Audit trail#

Scope changes are audited: every scope added to a key by ?extend_group_scopes=true (or by the platform team) writes a row to api_key_scope_audits with the scopes added, the reason, and the acting key or user.

Individual requests are not logged per key. An api_key_logs table exists in the schema, but nothing writes to it, and last_used_at is not updated. To answer "what did this key touch", use the effects instead: doc page revisions record their editor, and downloads record their asset.

Updated 2026-11-15 01:58:03 View source (.md) rev 3