Scopes on Resources

API Resources use OAuth scopes tied to Role-Based Access Control (RBAC). MCP Server Resources use MCP OAuth scopes that can map to Connection scopes when tools need external credentials.

For how OAuth clients request these scopes, see Inbound Apps (APIs) and Agentic clients (MCP).

For controlling which clients can receive which scopes, see Policies.

API Resources

API Resources define the permission catalog for a protected API:

• Scopes — What a client may do on the API (contacts.read, orders.write). These appear in the token's scope claim and are what you typically enforce per route.
• Roles — Descope RBAC roles mapped to each scope. Roles carry permissions your backend may already understand. When a scope is granted, the mapped role(s) can appear in the token's roles claim so APIs can authorize from roles/permissions instead of maintaining a separate OAuth-scope map.

Permission scopes

Define roles and permissions under Authorization → RBAC, or via Management SDKs. Assign roles to users in the users table, through SSO group mapping, or programmatically.

How scope ↔ role mapping works

On an API Resource, each permission scope can be linked to one or more Descope roles. That mapping does two related jobs:

1. Eligibility (user-delegated flows) — A user can only consent to (and receive) a scope if they hold at least one of the roles mapped to that scope (or otherwise satisfy RBAC for it).
2. Token claims — When a scope is granted on a Resource access token, Descope includes the roles mapped to that granted scope in the token's roles claim (see User-delegated vs M2M below).

So if scope orders.write is mapped to role Order Editor, a token that includes orders.write can also include "roles": ["Order Editor"]. Your API can then resolve permissions under Order Editor the same way it does for first-party sessions, instead of hard-coding every OAuth scope in the backend.

{
  "sub": "user123",
  "aud": ["https://api.example.com"],
  "scope": "contacts.write",
  "roles": ["Sales Manager"]
}

User-delegated (Authorization Code and CIBA)

Interactive grants (authorization code, CIBA) involve a user who authenticates and consents.

Important details:

• roles mirrors granted scopes, not the user's full role set. If the user holds Admin, Sales Manager, and Sales Rep, but only consents to contacts.read (mapped to Sales Rep), the Resource token typically includes roles: ["Sales Rep"]—not every role on the user.
• If the user lacks a required role for a scope, they cannot consent to that scope and it will not appear on the token.
• Consent accumulates. There is one consent record per user per app or client, and newly granted scopes are added to it rather than replacing earlier ones. A user who consented to contacts.read and later to contacts.write holds both, so a later request for contacts.read alone issues a token without prompting again. See How Consent Accumulates.
• To put all of the user's tenants, roles, and permissions on the JWT regardless of which scopes were approved, enable Always include all user authorization info on the token on the Inbound App. See Scope Token Settings. That setting is separate from scope↔role mapping on the Resource. For an MCP Server Resource, the same setting lives on the MCP server, or on its dynamic registration template if it uses one.

Example: user-delegated CRM access

1. A partner Inbound App requests contacts.write.
2. The user must hold Sales Manager (the role linked to that scope) to consent to it.
3. On success, the token will include the granted scope: "contacts.write" and the mapped roles: ["Sales Manager"].
4. Your API can authorize using roles / permissions under Sales Manager, or require contacts.write in scope—or both.

Machine (M2M) and autonomous clients

Client credentials, JWT bearer, and autonomous Agentic Clients have no interactive user consent. There is no end-user role check at consent time.

Use this when many M2M clients share tags and Policies grant each tag a specific Resource + scope set. Backends that already authorize from Descope roles and permissions can read roles on the M2M token the same way they do for user tokens, without mapping every OAuth scope in application code.

Example:

1. API Resource scope claims.read is mapped to role Claims Reader (with permissions your APIs already check).
2. A Policy allows clients with tag smithrx-batch to receive claims.read on that Resource.
3. A client_credentials token for such a client includes scope: "claims.read" and roles: ["Claims Reader"].

User-information scopes

Scopes that share user information with a client, such as profile and email, aren't defined on a Resource. They're attribute scopes, defined once for the project and added to each Inbound App or Federated OIDC App, where they map to the claims that appear in tokens and the /userinfo response.

Enforce on your API

Validate the JWT, then enforce aud, scope, and—if you authorize via RBAC—roles / permissions. See Enforce scopes and Resource claims.

MCP Server Resources

MCP Server Resources define tool-level OAuth scopes for an MCP server. Instead of mapping Resource scopes to RBAC roles, you can map Resource scopes to Connection scopes for when a tool needs credentials from the Connections vault.

When a client is granted mcp:hubspot, your server can fetch the matching Connection token for HubSpot without storing third-party secrets in the MCP server itself.

Defined MCP scopes appear in the server's discovery document under scopes_supported.

For more configuration details, see MCP server scopes.

Related

• Resources — API and MCP Server Resource overview
• Policies — Which clients and users may receive which scopes
• Creating Inbound Apps — Scope token settings and consent behavior
• Session validation — Enforce aud, scope, and roles on your API