OAuth Custom Scopes
OAuth Custom Scopes is the Salesforce feature that lets administrators define org-specific OAuth scopes beyond the standard scopes (api, refresh_token, full, openid, etc.). Custom scopes enable fin…
Definition
OAuth Custom Scopes is the Salesforce feature that lets administrators define org-specific OAuth scopes beyond the standard scopes (api, refresh_token, full, openid, etc.). Custom scopes enable fine-grained authorization where the standard scopes are too broad: a custom scope might grant access to specific custom objects, allow specific business operations, or represent a specific permission level within a custom integration. Once defined, custom scopes can be requested by Connected Apps just like standard scopes.
The feature addresses a specific gap. Standard OAuth scopes are coarse-grained: api grants all object access; the only finer control comes through profile and permission set assignments on the user. Custom scopes let the integration declare its access intent at the token level, and the platform can enforce based on the scope. This is particularly useful for multi-tenant integrations where the same Connected App needs to request different levels of access depending on the deployment context.
How OAuth Custom Scopes work
Why custom scopes matter
Without custom scopes, OAuth authorization is binary: the Connected App has api scope or it does not. Real applications need finer differentiation: read-only access versus read-write, access to specific business processes, deployment-specific access. Custom scopes provide the declarative mechanism for this differentiation, with the scope name communicated to users during authorization and stored in the access token.
Defining a custom scope
Setup > Identity > OAuth Custom Scopes > New. Provide a name, description, and any restrictions. The name appears in the OAuth consent prompt (so name it meaningfully). After saving, the scope is available for Connected Apps to request. Custom scopes do not directly grant access; they communicate intent, and downstream Apex or middleware enforces based on the scope.
Requesting custom scopes
Connected Apps reference custom scopes in their OAuth Scopes configuration. During the OAuth flow, the requesting application includes the scope in the authorization request. The user sees the scope in the consent prompt; granting authorizes the scope. The access token includes the scope claim, which downstream code can inspect.
Enforcement is code-side
Custom scopes do not directly restrict platform-level data access. The platform delivers the scope in the token; downstream code (Apex, middleware, the integration itself) must inspect the scope and enforce. This is the trade-off: custom scopes are flexible (declare any intent) at the cost of requiring custom enforcement logic.
User consent prompt
When a user authorizes a Connected App requesting custom scopes, the consent prompt lists each scope with its description. Write descriptions carefully; the user sees them and decides whether to grant. Vague or misleading descriptions defeat the security purpose of explicit consent.
Multi-tenant federation use case
Custom scopes excel for multi-tenant federation scenarios. A SaaS platform integrating with multiple Salesforce orgs can define org-specific scopes representing different access levels. The integration requests appropriate scopes per deployment, with users seeing clear consent for each. Without custom scopes, the integration would need separate Connected Apps per access level, which is operationally heavier.
Limits and lifecycle
Custom scopes have org-level limits on count. Manage them as carefully as standard configuration: name consistently, document purpose, audit quarterly for unused scopes. Like other metadata, custom scopes deploy through changesets and SFDX, but the deployment is metadata-only; the runtime enforcement code must be deployed separately.
Create and enforce a custom OAuth scope
Building a custom scope involves defining the scope, configuring Connected Apps to request it, and implementing enforcement logic. The steps below cover the full lifecycle.
- Identify the access pattern
Document the access level the scope represents. Examples: read-only product catalog, write-access to orders, admin-level config access.
- Define the scope
Setup > Identity > OAuth Custom Scopes > New. Name it (use meaningful naming convention), write a clear user-facing description, save.
- Add to Connected App
Edit the relevant Connected App. Add the custom scope to OAuth Scopes. Save.
- Implement enforcement logic
In Apex (or middleware), inspect the access token to extract scope claims. Enforce the scope-specific restrictions before granting data access.
- Test OAuth consent flow
Run the OAuth flow as a sample user. Confirm the consent prompt displays the scope with the expected description.
- Test enforcement
With a token granted the scope, confirm enforcement code allows access. With a token lacking the scope, confirm denial.
- Document the scope
Maintain a registry of custom scopes with name, purpose, enforcement logic location. New admins inherit a black box without it.
Identifier used in OAuth requests. Meaningful naming convention important.
User-facing text in consent prompt. Write carefully.
Apps that can request the scope.
Apex or middleware that inspects token scope and enforces.
Scopes deploy through changesets and SFDX.
- Scopes communicate intent only. Without enforcement code, the platform delivers the scope but does not restrict.
- Vague scope descriptions defeat the consent security purpose. Write user-facing descriptions carefully.
- Org-level scope count limits apply. Audit periodically; bloat reduces security signal.
- Scope deployment is metadata-only. Enforcement logic must be deployed separately and kept in sync.
- Scope changes after deployment can break integrations expecting specific scope names. Plan migrations carefully.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is the primary benefit of OAuth Custom Scopes for Salesforce administrators?
Q2. Why is understanding OAuth Custom Scopes important for Salesforce admins?
Q3. In which area of Salesforce would you typically find OAuth Custom Scopes?
Discussion
Loading discussion…