Permissions and Scopes

Reference for all API and MCP permission scopes, how they control access, and best practices.

Shocking Energy uses scopes to control what API keys, OAuth tokens, and MCP connections can access. Scopes follow the resource.action pattern (e.g. jobs.read) and determine which tools, resources, and API endpoints are available.

How scopes work

When you create an API key or OAuth application, you assign it one or more scopes. These scopes control:

MCP tools — which tools appear when an AI assistant calls tools/list
MCP resources — which resources are visible via resources/list
REST API endpoints — which endpoints the key can access
Write access — whether the key can create, modify, or delete data

Scopes are enforced server-side. Even if an AI assistant or client requests a tool outside its scope, the server will not expose it.

Scope reference

Resource scopes

Scope	Description	MCP tools	REST API
`jobs.read`	List, view, count jobs and audit history	`jobs_list`, `jobs_get`, `jobs_count`, `jobs_audits`	`GET /v1/jobs`, `GET /v1/jobs/:id`
`jobs.write`	Create, assign, start, complete, cancel, and abort jobs	All `jobs_*` write/destructive tools	`POST /v1/jobs`, `PATCH /v1/jobs/:id`
`flows.read`	List and view flows and flow groups	`flows_list_groups`, `flows_get_group`, `flows_list_by_group`, `flows_get`	`GET /v1/flows`
`flows.write`	Regenerate and resend flows	`flows_regenerate`, `flows_resend`	`POST /v1/flows/:id/regenerate`
`assets.read`	View assets, asset types, and asset history	`assets_list`, `assets_get`, `assets_history_list`, `asset_types_list`	`GET /v1/assets`, `GET /v1/assets/:id`
`assets.write`	Create and manage assets, history restores, and asset type lifecycle	`assets_create`, `assets_update`, `assets_archive`, `asset_types_create`, `asset_type_versions_publish`	`POST /v1/assets`, `POST /v1/assets/:id/archive`
`projects.read`	View projects, templates, clients, and sites	`projects_list`, `projects_get`, `project_templates_list`, `clients_list`, `sites_list`	`GET /v1/projects`, `GET /v1/project-templates`, `GET /v1/clients`, `GET /v1/sites`
`projects.write`	Create/manage projects, revisions, templates, links, clients, and sites	`projects_create`, `projects_revisions_create`, `projects_jobs_add`, `project_templates_create`, `clients_create`, `sites_create`	`POST /v1/projects`, `POST /v1/project-templates`, `POST /v1/clients`, `POST /v1/sites`
`invoices.read`	View invoices and invoicing setup (profile/contracts/rates)	`invoices_list`, `invoices_get`, `invoicing_profile_get`, `invoicing_contracts_list`, `invoicing_rates_list`	`GET /v1/invoices`, `GET /v1/invoicing/profile`, `GET /v1/invoicing/contracts`, `GET /v1/invoicing/rates`
`invoices.write`	Create/manage invoice drafts, lifecycle actions, contracts, rates, and templates	`invoices_draft_upsert`, `invoices_finalize`, `invoices_approve`, `invoicing_profile_upsert`, `invoicing_contracts_create`, `invoicing_rates_create`, `invoice_template_upsert`	`POST /v1/invoices/draft`, `POST /v1/invoices/finalize`, `POST /v1/invoicing/profile/upsert`, `POST /v1/invoicing/contracts`, `POST /v1/invoicing/rates`
`team.read`	View team info, members, job types, suppliers, and MCP resources	`team_info`, `team_members`, `team_job_types`, `team_job_type_detail`, `team_suppliers`	`GET /v1/team`
`search.read`	Semantic search across all team data	`search_global`	`GET /v1/search`
`metrics.read`	View job, flow, and log metrics	`metrics_jobs`, `metrics_jobs_by_type`, `metrics_logs_by_type`, `metrics_flows_by_time`	`GET /v1/metrics/*`
`sip.write`	Submit SIP worksheet data	—	`POST /v1/sip`

Shortcut scopes

Scope	Expands to
`apis.all`	Every resource scope (all read and write permissions)
`apis.read`	Every `*.read` scope (`jobs.read`, `flows.read`, `assets.read`, `projects.read`, `invoices.read`, `team.read`, `search.read`, `metrics.read`)

Scope expansion

When a key or token has a shortcut scope, it is expanded server-side:

apis.all expands to all resource scopes — the key can read and write everything
apis.read expands to all read scopes — the key can read everything but cannot modify data
No scopes assigned — API keys with no explicit scopes default to apis.all for backwards compatibility

You can combine apis.read with specific write scopes:

apis.read + jobs.write

This gives read access to everything plus write access to jobs only.

Scope behaviour in MCP

Scopes control which MCP capabilities are available to a connected AI assistant:

Tools

Each tool belongs to a scope group. If the key does not have the required scope, the tool does not appear in tools/list.

Read tools (e.g. jobs_list) require the *.read scope
Write tools (e.g. jobs_create) require the *.write scope
Destructive tools (e.g. jobs_cancel) also require the *.write scope

Resources

MCP resources (team info, members, job types, suppliers) require the team.read scope. If the key does not have team.read, no resources appear in resources/list.

Prompts

MCP prompts (job health check, flow analysis, etc.) are always available regardless of scope. However, the tools they reference may not be available if the key lacks the required scopes.

Choosing scopes

For AI assistants (MCP)

Use case	Recommended scopes
Read-only dashboard / analytics	`apis.read`
Job management assistant	`jobs.read`, `jobs.write`, `team.read`
Asset operations assistant	`assets.read`, `assets.write`, `team.read`
Project delivery assistant	`projects.read`, `projects.write`, `team.read`
Billing/invoice assistant	`invoices.read`, `invoices.write`, `team.read`
Full operations assistant	`apis.all`
Flow monitoring	`flows.read`, `metrics.read`
Search only	`search.read`

For REST API integrations

Use case	Recommended scopes
Reporting dashboard	`apis.read`
Job creation automation	`jobs.read`, `jobs.write`
Asset sync integration	`assets.read`, `assets.write`
Project sync integration	`projects.read`, `projects.write`
Billing integration	`invoices.read`, `invoices.write`
Complete integration	`apis.all`
SIP submission	`sip.write`, `jobs.read`

Best practices

Principle of least privilege — grant only the scopes each integration needs. Start with read-only and add write scopes when required.
One key per integration — create a dedicated API key for each AI client or integration. This allows you to revoke access for one integration without affecting others.
Review destructive access — the *.write scope enables both write and destructive operations (cancel, abort). AI clients will prompt for confirmation before calling destructive tools.
Use apis.read for analytics — dashboards and reporting tools rarely need write access. Use apis.read to prevent accidental modifications.
Audit access periodically — review your API keys and OAuth applications in Settings > Developer to ensure no unused keys have broad permissions.

How access is enforced

Access control is enforced at multiple layers:

Authentication — every request must include a valid API key (Bearer se_*) or OAuth access token (Bearer se_oauth_*). Invalid or expired credentials return 401 Unauthorized.

Scope expansion — shortcut scopes (apis.all, apis.read) are expanded to their concrete resource scopes.

Tool filtering — MCP tools are only registered if the key has the required scope. Tools outside the key's scope do not appear and cannot be called.

Endpoint enforcement — REST API endpoints check the key's scopes before processing the request. Requests outside scope return 403 Forbidden.

Permissions and Scopes

On this page