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 client access to specific scopes of these Resources, see the Policies section of our docs.

API Resources

API Resources define the permission catalog for a protected API. Scopes express what a client may do; Descope roles express who the user is allowed to be when granting or receiving those scopes.

Permission scopes

Field	Description
Name	Scope string in authorize requests and tokens (e.g. `shipments.read`)
Description	Shown on consent screens when an Inbound App requests access
Roles	RBAC roles a user must hold to consent to or receive this scope

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.

Role-gated consent

If a scope requires a role the user does not have, they cannot grant consent for that scope. Only users with matching RBAC roles see and approve those permissions during the Inbound App flow.

API Resources can also define scopes that gate which user attributes are shared with a client (email, name, custom attributes). Each scope maps to a Descope user attribute; access still follows RBAC on the underlying data.

Enforce on your API

Tokens include scope (space-separated) and typically roles in JWT claims:

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

Your API should require the correct scope for each route and may check roles for sensitive operations. See Developing APIs with OAuth.

Example: scope and role on a CRM API

Suppose you protect a CRM API as an API Resource with these definitions:

Scope	Mapped Descope role	What it allows
`contacts.read`	`Sales Rep`	List and view contacts
`contacts.write`	`Sales Manager`	Create and update contacts

An Inbound App for a partner integration requests contacts.write during authorization. Descope checks RBAC before consent:

The user must hold the Sales Manager role — the role linked to contacts.write on the Resource.
If they do, they can approve the scope on the consent screen and receive a token with scope: "contacts.write" and roles: ["Sales Manager"].
If they only have Sales Rep, they can consent to contacts.read but not contacts.write.

The partner asks for a scope (what the app may do). Descope uses roles (who the user is) to decide whether that scope can be granted.

Your API then validates the token's scope on each route and can use roles for stricter checks on admin-only operations.

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.

Field	Description
Scope name	Machine-friendly string your MCP server enforces (e.g. `mcp:schedule_meetings`)
Connection scopes	OAuth or API permissions on linked Connections to fetch at tool runtime
Consent description	Text shown on the user consent screen
Mandatory	Whether the scope must be consented to (optional scopes can be declined)

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.

RBAC and MCP Server Resources

Role-based checks for MCP flows use Agentic Identity Hub policies (for example user.roles CONTAINS "scheduler") and consent-flow logic—not scope-to-role fields on the MCP Server Resource definition. API Resources use scope ↔ RBAC on the Resource; MCP Server Resources use scope ↔ Connection mapping on the Resource.

For more configuration details, see MCP server scopes.

Machine (M2M) clients

Client credentials and autonomous agentic clients do not run interactive consent. Scope grants follow client configuration and policies, not per-user RBAC at consent time.

Was this helpful?