Scopes, API tokens, OAuth, and MCP

See the scope reference for every permission, its description, supported restrictions, and token delegation.

Programmatic access should be easier to revoke and narrower than a human administrator session. The automation owner defines the required workflow, the resource owner approves its reach, and the security owner reviews credential lifetime and storage. Success means the integration can perform its intended action, is denied elsewhere, and can be rotated without interrupting unrelated systems.

Users manage API tokens under Profile > Authorizations > API Tokens. Secrets are shown once. Store them in a secret manager, assign the minimum scopes, and revoke unused tokens.

OAuth clients delegate user authority with explicit redirect URIs and consent. Remote MCP uses the same resource and scope model as REST and the Console; it is not a privileged back door.

Use separate credentials for CI, monitoring, and interactive tools. Avoid long-lived administrator tokens. Resource-scope automation to the exact nodes, Routes, workloads, databases, or Pages Projects it owns.

Regular gw_ API credentials and OAuth credentials do not enter the Gateway Inference data plane. Inference uses dedicated gwi_ user tokens.

Audit token creation, use, and revocation. Rotate immediately after suspected disclosure and verify active sessions separately.

Choose the credential type

Credential	Use
Session	Interactive Operations Console access
API token	Direct automation owned by one Gateway user
OAuth client	Delegated user authorization and third-party applications
Remote MCP OAuth	Tool clients that act through Gateway’s MCP surface
Inference token	Requests to the separate Gateway Inference data plane

Do not substitute one type for another merely because it is easier to copy. Credential type determines consent, revocation, scope evaluation, audit purpose, and the endpoint family it can access.

Create a least-privilege token

1. Identify the exact operations and resources the automation owns.
2. Create a dedicated user or service identity when attribution should be separate.
3. Assign the minimum global and resource scopes.
4. Create the token and capture the secret once.
5. Store it in a secret manager and inject it at runtime.
6. Test one allowed request and one denied request.
7. Record the owner, purpose, expiry/rotation expectation, and dependent system.

Avoid embedding tokens in repository URLs, command history, screenshots, or logs. A masked UI value cannot be recovered later; create a replacement and revoke the old token when the secret is lost.

OAuth and MCP

Register exact redirect URIs and reject wildcard redirect behavior. Review requested scopes during consent and separate development clients from production clients. Remote MCP tools use the same authorization checks and resource visibility as REST and the Console; tool discovery does not grant permission to execute a tool.

Handle authorization failures distinctly:

• 401: missing, expired, or invalid authentication;
• 403: authenticated identity lacks the required scope or entitlement;
• 409: current resource state or quota conflicts with the operation;
• 422: request validation failed.

Rotation and incident response

Create the replacement, update the dependent system, verify successful use, and then revoke the old credential. After suspected disclosure, revoke first when operationally safe, inspect audit activity, invalidate related sessions separately, and rotate any downstream secret that may have been exposed.

Scope design and ownership

Start from the operation, not from a role name. List the exact read and mutation calls the integration needs, then bind resource scopes to the smallest stable ownership boundary: a Folder, Node, Route, workload, database, or Pages Project. Add a global scope only when the workflow genuinely crosses all resources of that type. Separate view, reveal, export, console, mount, secret, and lifecycle permissions; ordinary read access must not imply access to credentials or host-sensitive operations.

Every credential needs a human owner, a machine consumer, a purpose, an environment, and a removal condition. A token used by CI should not also be used for an operator’s terminal session. Production and non-production OAuth clients should have different client IDs, redirect URIs, secrets, and consent records. When ownership changes, transfer or replace the credential rather than leaving it attached to a departed user’s account.

Operational verification

Before enabling automation in production:

1. call a harmless read endpoint with the new credential;
2. perform one intended mutation against a disposable resource;
3. prove an out-of-scope resource is hidden or denied;
4. confirm audit attribution identifies the expected user or OAuth client;
5. verify token values, authorization headers, and callback parameters are redacted from logs;
6. revoke the credential and prove the consumer fails closed;
7. install the replacement and document the tested rotation order.

Revoking an API token does not automatically terminate browser sessions, OAuth grants, inference tokens, or credentials stored in external providers. During an incident, inventory each credential family separately.