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.