API keys

API keys

The platform exposes a versioned REST API at /api/v1. To use it, an integration needs an API key (a Sanctum personal access token, in Laravel terms).

When to issue a key

Three common scenarios:

• Outbound integration — the trust runs custom scripts or dashboards that read Keystone data
• Inbound integration — an external system (an HR app, a procurement tool) needs to create/update Keystone records
• Mobile app — the discovery agent uses an API key to push device data

Issuing

In Platform admin → Settings → API keys:

1. Click New key
2. Give it a name (descriptive, e.g. “Wonde sync agent”)
3. Pick the scope — which abilities it has (tickets:read, assets:write, etc.)
4. Pick the workspace — the key is scoped to one workspace
5. Set an expiry — recommended; 1 year is a common cycle
6. Click Create

The key is shown once, in the toast. Copy it immediately. After you dismiss the toast, the platform never reveals it again — only its hash is stored. If you lose it, revoke and create a new one.

Scopes

The standard scopes:

Scope	Grants
tickets:read	List, view, search tickets
tickets:write	Create, update, comment on tickets
assets:read	Read the asset register
assets:write	Update assets (e.g. discovery agent’s bread-and-butter)
people:read	Read people records (staff, pupils with PII filter)
governance:read	Read risks, policies, compliance
reports:read	Run pre-built reports
webhooks:write	Subscribe to events (see Webhooks article)
*	Everything; reserve for first-party integrations only

Scope tightly. A read-only dashboard doesn’t need write scopes.

Authentication

API requests authenticate by Bearer header:

Authorization: Bearer ks_live_<token>
X-Workspace-Id: <workspace-uuid>

The X-Workspace-Id header is required for keys that have multi-workspace access (rare). For single-workspace keys it’s inferred.

Rate limits

The default is 60 requests/minute per key. High-volume integrations can request a higher limit per-key. Hitting the limit returns 429 with a Retry-After header.

Auditing key usage

The keys index shows last-used timestamp + count for each key. Keys not used in 90 days are flagged for review — typically they’re dead integrations whose author left the trust.

Revoking

Revoke a key when the integration is decommissioned or the key is suspected leaked. Revoked keys can’t be reactivated; create a new one.

Don’t delete keys from the audit log — revoke. Deletion would lose the key’s history.

Rotating

For long-lived integrations, rotate keys annually:

1. Issue a new key with the same scope
2. Update the integration to use the new key
3. Verify it’s working (check the new key’s last-used updates)
4. Revoke the old key

The rotation window with both keys live is typically 24 hours.