Permissions & scopes
Scopes a key can carry.
A key carries a set of scopes. Each endpoint requires a specific scope; a call without it returns 403 forbidden with the missing scope named.
| Scope | Friendly name | Endpoints it unlocks |
|---|---|---|
ai_explain | Interpret & explain | interpret, conversations, messages, embed tokens |
ai_generate | Generate code | generate (proposes code; never persists) |
analysis_tab | Run analyses | start & poll analyses |
code_read | Read code | read project source (/source) |
code_write | Edit & save project | save a new version (/versions) |
export_plc | Export to PLC format | start & download a PLC export |
export_pdf | Export to PDF | start & download a PDF report |
hmi_view | View HMI | read live values & history; carried by read-only embed tokens |
project_upload | Upload projects | ingest (create a project identity) |
Reading the project list (GET /projects) and one project's metadata (GET /projects/{id}) needs no extra scope — any valid key may discover the projects in its scope.
Generate and save are separate scopes on purpose. ai_generate only drafts a reviewable proposal; persisting it requires code_write. A generate-only key can never deploy a machine-bound version.
Project scope
A key may optionally be restricted to specific projects. When set, any project-targeted call to a project outside the scope returns 403 project_scope_forbidden.
A project-scoped key may add a version to an in-scope project, but can never create a new project identity via ingest. Creating new identities requires an unscoped key.