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 Opfield 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 Opfield user
OAuth client	Delegated user authorization and third-party applications
Remote MCP OAuth	Tool clients that act through Opfield’s MCP surface
Inference token	Requests to the separate Opfield 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.

What tokens can and cannot do in 2.11

API tokens and OAuth grants for the Opfield API or MCP can hold every permission scope except a short user-only list: the AI Workspace and AI sandbox scopes (ai:workspace:use, feat:ai:configure, ai:skills:manage, and ai:sandbox:*), mcp:use, inference:setup, admin:users:impersonate, and integrations:gitlab:sandbox:clone. Programmatic access can therefore manage Nodes and their configuration, users and groups, Opfield settings, integration and hosting connectors, hosting VMs, Relay operations, updates, inference administration, and the owner’s personal gwi_ inference keys. Every delegated scope stays bounded by the owner’s current permissions.

Some actions stay tied to an interactive browser session:

• creating API tokens and OAuth authorizations, and OAuth consent itself;
• AI Workspace chat and AI sandboxes;
• starting impersonation;
• signing in, and changing the owner’s own sign-in methods, MFA, passkeys, or sessions; a token that tries returns SELF_SIGN_IN_PROGRAMMATIC;
• managing personal GitLab credentials.

Because tokens can now hold administrative scopes, treat an administrator-scoped token like an administrator account: give it an owner, an expiry, and a narrow resource scope where possible.

Opfield 2.11 renamed several scopes. Token creation, OAuth scope parameters, and OAuth authorization edits still accept the old names for two releases and store the new ones; existing tokens and grants were converted during the update. A new token or OAuth request for a scope such as integrations:github:manage also receives the scopes that the update added for it (here repo:read) when you hold them; the consent screen shows them and you can untick them. Scopes that need manual approval, such as repo:write or pki:ca:export, are never added this way. See Retired scope names.

Restrict tokens and OAuth grants

A token or OAuth grant can be limited to folders, Nodes, or individual resources in the same way as a user’s permissions. A folder restriction covers the folder, its subfolders, and resources created in or moved into it later. See Restrict access to a folder.

• API tokens: in Profile > Authorizations > API Tokens, each selected scope that supports restrictions has its own picker for folders, Nodes, and resources. The picker offers only what you can use yourself.
• OAuth and MCP consent: restrictions start collapsed. A scope you hold broadly shows All resources · Restrict…; a scope you hold only for some resources shows No resources selected until you choose them. Limit selected scopes to folder… applies one folder to every selected scope of that folder’s resource type at once. You can change the scopes and restrictions of an existing OAuth authorization later under Profile > Authorizations.
• Git integrations: both forms restrict Git scopes to a connector, a GitLab group or project, or a GitHub owner or repository, with Add groups or projects… or Add owners or repositories… under each connector. Such a token is checked against its own restriction and against your current Git access on every repository operation, so it stops reaching a repository as soon as you lose access to it. See Git integration restrictions.

Opfield expands a token’s own folder and Node restrictions first and then limits the result by your current access, so a token never sees more than you do. A creation grant never counts as a view grant when you delegate it. If a client requests a broad scope that you hold only for some resources, Opfield narrows the grant to those resources.

OAuth and MCP

Register exact redirect URIs and reject wildcard redirect behavior. Review requested scopes during consent and separate development clients from production clients. Consent leaves high-risk scopes unchecked by default so that they must be selected explicitly—for example admin:system, admin:users, admin:groups, settings:gateway:edit, nodes:manage, proxy:raw:write, proxy:unrestricted, proxy:templates:manage, pki:ca:export, connector system credentials (integrations:*:use), integrations:ssh:use, paid or destructive hosting actions, storage:credentials:reveal, storage:iam, databases:backups:restore, and feat:ai:use. 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.

Expired OAuth authorization codes and tokens, and OAuth clients that have had no grant for 90 days, are removed by the Expired OAuth Grants housekeeping category; a refresh token is kept until it expires so that its reuse is still detected. See Housekeeping and retention.

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.