Permissions & scopes
Tools map to scopes.
A connection can only do what its credential is scoped for. With OAuth that's your membership permissions; with an API key it's the key's scopes. A call to a tool whose scope you lack returns a clear 403 forbidden naming the missing scope.
| Scope | Friendly name | Tools it unlocks |
|---|---|---|
ai_explain | Interpret & explain | plcs_interpret, plcs_mint_embed_token |
ai_generate | Generate code | plcs_generate_code |
analysis_tab | Run analyses | plcs_start_analysis, plcs_get_analysis |
code_read | Read code | plcs_get_project_source, plcs_search_context |
code_write | Edit & save project | plcs_save_version |
export_plc | Export to PLC format | plcs_export_plc (+ plcs_get_export / plcs_download_export) |
export_pdf | Export to PDF | plcs_export_pdf (+ plcs_get_export / plcs_download_export) |
hmi_view | View HMI | plcs_get_live_values, plcs_get_tag_history |
project_upload | Upload projects | plcs_ingest_project |
plcs_health, plcs_list_projects, and plcs_get_project need only a valid credential — no extra scope.
Generate and save are separate scopes on purpose. ai_generate only drafts a reviewable proposal; persisting it requires code_write. A generate-only connection can never deploy a machine-bound version.
Project scope
A key (or connection) may optionally be restricted to specific projects. When set, any tool call targeting a project outside that scope returns 403 project_scope_forbidden.