OAuth Custom Scopes
An OAuth custom scope is a permission you define in Salesforce to fine-tune what an external client app or connected app can access during an OAuth flow.
Definition
An OAuth custom scope is a permission you define in Salesforce to fine-tune what an external client app or connected app can access during an OAuth flow. The standard scopes (api, full, refresh_token, openid, web) are deliberately broad. A custom scope lets you describe a narrower slice of access, often access to a resource that lives outside Salesforce, and have that intent carried inside the issued access token.
The feature exists for a specific arrangement. Salesforce acts as the OAuth authorization provider, but the protected data sometimes sits behind an external API gateway that Salesforce knows little about. You create a scope such as order_status, Salesforce validates the user and stamps the scope onto the token, and the external gateway reads that scope to decide what to return. The user sees the scope description on the approval page and consents to it explicitly.
How OAuth custom scopes fit into a Salesforce-as-provider flow
What problem custom scopes actually solve
Standard Salesforce OAuth scopes answer a coarse question: can this app call the API at all, can it refresh its token, can it read the identity URL. They were never meant to describe access to data that Salesforce does not host. That gap shows up the moment a connected app needs to reach a resource behind your own API gateway, where Salesforce is only the login and token authority. A custom scope fills the gap by giving you a named permission that travels in the token. Salesforce documents the canonical example as an order_status scope. It permits an app to read customer order status and nothing else, so billing and payment data stay out of reach even though the same login was used. The scope is a contract between three parties. Your gateway defines a policy, Salesforce issues a token carrying the matching scope string, and the app presents that token. None of this changes what Salesforce itself exposes through its own APIs. It is purely about communicating fine-grained intent to an external system that trusts Salesforce to authenticate the user and assert which scopes were granted.
Salesforce plays authorization provider, not data owner
The mental model matters here, because it is easy to assume a custom scope tightens access to Salesforce records. It does not. In the supported pattern, Salesforce sits in front as the OAuth 2.0 authorization server. It owns the user identity, runs the consent screen, and mints the access token. The actual protected resource lives elsewhere, and Salesforce has limited knowledge of it. That is by design. You are reusing Salesforce login and its token machinery to guard an external API. When the app calls that external API, the API gateway inspects the token, finds the custom scope claim, and enforces its own policy. So the enforcement boundary is the gateway, not the platform. This is why the scope name you type in Setup must match the policy name configured on the external entity exactly. A mismatch means the token carries a scope string the gateway does not recognize, and the call is rejected. Treat the scope name as a shared key between two systems rather than a label you can freely rename later.
The approval page and explicit consent
Every custom scope you create has a Description, and that text is not just internal documentation. Salesforce shows the description on the OAuth approval page when a user authorizes the app. This is the consent moment. The user reads what the app is asking for and decides whether to grant it. A description like Read your order status tells the user something real. A vague string like access scope tells them nothing and quietly defeats the point of asking. The platform enforces some hygiene on this field. The description must be unique, contain only alphanumeric characters, and stay within 60 characters. If you support users in multiple languages, you can point the scope at a custom label instead of a literal description, and the label gets translated like any other. Plan the wording before you create the scope. Once apps are live and users have consented, changing a description retroactively changes what everyone sees, and consistency across your scopes makes the whole approval page easier to trust.
How the scope reaches the token
Creating a scope and assigning it to an app is not enough on its own. For most OAuth flows the requesting app must include the scope name in the scope parameter of its authorization request. Only the scopes the app actually asks for, and that the user grants, end up in the token. This keeps tokens minimal and lets one app request different scopes in different situations. There is a notable exception. With the OAuth 2.0 JWT bearer flow, when the external client app is pre-authorized, custom scopes are returned with the access token automatically. No interactive consent screen runs in that server-to-server pattern, so the assignment alone drives what the token carries. Once the token is issued, Salesforce includes the granted scopes in its response to the client. The app then forwards that token to the external API, which reads the scope claim. Knowing which flow you use tells you whether the scope parameter is mandatory or whether pre-authorization handles it, and that detail often explains why a token shows up missing the scope you expected.
Connected apps and the move to External Client Apps
You can assign custom scopes to a classic connected app, but Salesforce now steers new OAuth work toward External Client Apps, the successor framework for app integrations. The assignment lives in different places depending on which you use. For an External Client App, you open External Client Apps Manager, select the app, go to its Policies page, expand OAuth Policies, and pick the custom scopes to assign. For a connected app, the custom scope appears alongside standard scopes in the app OAuth settings. Either way the permission to do this work is Manage External Client Apps, and the feature is available across Group, Professional, Enterprise, Performance, Unlimited, and Developer editions, in both Lightning Experience and Salesforce Classic. There is also an optional Include on well-known endpoint setting. Turning it on lists the scope in the app OpenID Connect discovery document, which helps client developers learn the available scopes programmatically. If you are building a new integration today, default to External Client Apps so your scope assignments sit in the framework Salesforce is actively investing in.
Sandbox refresh and the lifecycle gotcha
Custom scopes carry an operational trap that bites teams during release work. OAuth custom scopes are not included when you refresh a sandbox. After a refresh, the scopes are gone from the apps that referenced them, and you have to reassign them. If a sandbox is part of your release pipeline, build that reassignment into your post-refresh checklist, or integration tests that depend on a scope will fail for a reason that looks unrelated. Beyond refreshes, treat scopes like any other metadata you own over time. Give each one a clear, stable name, write down which external policy it pairs with, and review the list periodically so retired scopes do not linger. Because the name is a shared key with an external gateway, renaming is not a free action. Coordinate any change with the team that owns the gateway policy. A small amount of documentation here, recording the scope name, its description, the app that requests it, and the gateway it maps to, saves a lot of confusion when someone inherits the integration months later.
How to create and assign an OAuth custom scope
Create an OAuth custom scope in Setup, then assign it to the app that will request it. You need the Manage External Client Apps permission. Decide the scope name with whoever owns the external API gateway first, because the name has to match the policy on that side exactly.
- Open OAuth Custom Scopes
From Setup, type Custom Scopes in the Quick Find box and select OAuth Custom Scopes. Click New Custom Scope to start a definition.
- Name the scope
Enter a Name that begins with a letter and uses only letters, numbers, and underscores, with no spaces. Match it to the policy name defined on your external entity, since the gateway compares the two.
- Write a consent-friendly description
Enter a Description under 60 characters that a user will read and understand on the approval page. For multi-language orgs, point the scope at a custom label instead of literal text.
- Decide on the well-known endpoint
Leave Include on well-known endpoint unchecked unless you want the scope published in the app OpenID Connect discovery document for client developers to discover. Save the scope.
- Assign the scope to an app
For an External Client App, open External Client Apps Manager, select the app, go to Policies, expand OAuth Policies, choose the custom scope, and save. For a connected app, add it in the app OAuth settings.
Unique scope identifier; starts with a letter, alphanumeric and underscores only, no spaces. Must match the external gateway policy name.
Unique, alphanumeric, 60 characters or fewer. Shown to users on the OAuth approval page, or replaced by a custom label for translation.
- Custom scopes are dropped on a sandbox refresh; reassign them to your apps afterward or dependent flows break.
- The scope name must exactly match the policy name on the external entity, so rename only in coordination with the gateway owner.
- For most flows the app must send the scope in the scope parameter; only the JWT bearer flow for pre-authorized apps returns it automatically.
Prefer this walkthrough as its own page? How to OAuth Custom Scopes in Salesforce, step by step
Trust & references
Cross-checked against the following references.
- OAuth Custom ScopesSalesforce
- Create an OAuth Custom ScopeSalesforce
Straight from the source - Salesforce's reference material on OAuth Custom Scopes.
- Assign an OAuth Custom Scope to a Connected AppSalesforce
- OAuth Tokens and ScopesSalesforce
Hands-on resources to go deeper on OAuth Custom Scopes.
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 does the OAuth Custom Scopes feature let an administrator do?
Q2. Where in Setup does an admin define a new OAuth Custom Scope?
Q3. How is an OAuth Custom Scope actually enforced once it is in the access token?
Discussion
Loading discussion…