Authentication
API keys.
Every request carries an API key as a bearer token. The key is the tenant — your organization is resolved from the credential, never from the URL.
http
Authorization: Bearer plck_live_8f2a…Minting, scoping & revoking
Keys are managed in the app at Settings → API Keys (owner/admin only):
- Create — name the key, pick its permission scope with human-readable toggles, optionally restrict it to specific projects.
- Reveal once — the secret is shown exactly once at creation and never again. Store it safely; if you lose it, revoke and recreate.
- Revoke — immediate. The next call with a revoked key fails with
401 key_revoked.
Scoping keys by role
Give each key only the scopes its integration needs. Two common shapes:
| Role | Scopes on the key | Can |
|---|---|---|
| Operator / technician | ai_explain + hmi_view | Ask questions and view answers; read-only. |
| Controls engineer | + analysis_tab, project_upload | Also run analyses and ingest projects. |
For a browser/iframe, never ship an API key. Mint a read-only embed token from your backend instead.