Documentation / API Token Scopes and Permissions / How API Scopes Work

How API Scopes Work

Understand scope storage, published scope labels, endpoint role checks, and token review workflows.

PanelConfig stores scope labels for each API token in api_token_scopes. The public API page also publishes scope labels such as domains.read, websites.read, and platform.read. Endpoint files authenticate tokens and apply role/account checks. Scope labels document integration intent and support consistent token review in PCAdmin.

What This Means

TopicCurrent behavior
Scope storageLive: scope labels are stored when a token is created.
Scope displayLive: PCAdmin lists stored scopes for each token.
Scope reviewPublished labels are stored and reviewed in PCAdmin.
Role enforcementLive for admin-only resources through pc_user_is_admin().
Account filteringLive on many resource endpoints for non-admin users through account-id filters.

Operator Guidance

Continue entering meaningful scope labels because they document intent and prepare integrations for strict enforcement later. For high-risk production environments, do not rely on scope labels alone until the deployed build includes explicit scope checks.

Planned Enforcement Flow

flowchart TD
    A[API Request] --> B[Bearer Token Valid]
    B --> C[Required Scope Resolved]
    C --> D{Token Has Scope or *}
    D -- No --> E[403 Forbidden]
    D -- Yes --> F[Role and Account Visibility]
    F --> G[Read or Queue Operation]
Admin Tokens vs User Tokens →