OAuth Custom Scopes
OAuth Custom Scopes is a Setup page for creating and managing custom OAuth scopes that define granular access permissions for Connected Apps.
Definition
OAuth Custom Scopes is a Setup page for creating and managing custom OAuth scopes that define granular access permissions for Connected Apps. Custom scopes allow administrators to control precisely what data and operations each external application can access beyond the default OAuth scopes provided by Salesforce.
In plain English
“Here's a simple way to think about it: OAuth Custom Scopes make least-privilege access actually achievable. Default scopes are coarse; custom scopes let you define exactly what each Connected App can do - "read Cases only", "update Accounts only".”
Worked example
The admin at CloudServe creates a custom OAuth scope called "read_orders" that grants read-only access to the Order and Order Item objects. When a third-party shipping integration connects via OAuth, it requests only the "read_orders" scope, ensuring it can access order data but cannot modify records or access other objects like Contacts or Opportunities.
Why OAuth Custom Scopes make least-privilege access actually achievable
The default OAuth scopes Salesforce ships (full, api, refresh_token, etc.) are coarse - give this app full API access is one toggle, with no in-between for read these specific objects. OAuth Custom Scopes is the page that lets you define your own. Create a scope named ReadOnly-Cases, attach it to a Connected App, and the access token issued can do exactly that and nothing more. The result is much tighter, more auditable integration access.
The reason this matters mostly to security-conscious teams is that the alternative is to trust every Connected App with the full keys to the platform. For low-risk internal apps that's fine; for partner integrations, vendor-supplied tooling, or apps handling sensitive data, custom scopes turn the question of what an app can do from anything into exactly this list. Define them once, attach them as you onboard each new app, and audit the catalog as part of your routine integration review.
How to set up OAuth Custom Scopes
OAuth Custom Scopes let you define your own OAuth scopes for Connected Apps — beyond the standard api / refresh_token / openid scopes. Useful for fine-grained access control between Connected Apps and your custom Apex APIs.
- Open Setup → OAuth Custom Scopes
Setup gear → Quick Find: OAuth Custom → OAuth Custom Scopes.
- Click New OAuth Custom Scope
Top-right.
- Set Name and Description
Name is the OAuth scope identifier (e.g., "orders.read"). Description for admin reference.
- Save
Scope is now available. Reference from Connected Apps.
- In a Connected App: tick this scope under Selected OAuth Scopes
App Manager → Connected App → Edit → OAuth Scopes section → tick the custom scope.
- Validate scope in Apex
Apex: System.UserInfo.getOAuthScopes() returns the scopes granted. Check for the custom scope before allowing access.
OAuth scope identifier. Should follow OAuth 2.0 conventions (lowercase, dot-separated).
Admin-facing only.
- Custom scopes are validated only by your code. Salesforce's OAuth flow grants the scope; your Apex must check for it via getOAuthScopes(). Without the check, the scope is decorative.
- Custom scopes don't change Salesforce's API permissions. They're a layer your code uses; Salesforce APIs still respect Profile + Permission Set grants regardless of OAuth scope.
- Renaming a custom scope breaks Connected Apps that reference the old name. Treat scope names as semi-permanent.
How organizations use OAuth Custom Scopes
Built custom scopes for partner integrations; previously over-broad permissions narrowed to exactly what each integration needs.
HIPAA compliance team uses custom scopes to ensure no integration accesses PHI it doesn't need.
Vendor-supplied tooling uses custom scopes; the vendor never has more access than the specific use case requires.
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…