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.
Real-World 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 Matters
OAuth Custom Scopes in Salesforce allow administrators to define granular, named permissions that control what specific data and operations an external application can access when authenticating via OAuth. While Salesforce provides built-in scopes like 'api', 'web', and 'refresh_token', custom scopes let you create purpose-specific permissions such as 'read_orders' or 'manage_inventory'. When an external application authenticates, it requests only the custom scopes it needs, and the Connected App enforces that the application cannot access data or operations beyond those scopes. This principle of least privilege significantly reduces the blast radius if an integration is compromised.
As organizations connect more external applications to Salesforce, the default broad scopes become a security concern. Without custom scopes, a third-party shipping integration with 'api' scope can technically access Contacts, Opportunities, and any other object — far more than it needs. Custom scopes enforce precise boundaries, ensuring each integration accesses only what it requires. This granularity becomes critical during security audits, vendor assessments, and data privacy compliance. Organizations that implement custom scopes can demonstrate to auditors exactly which data each external system can access, transforming API security from trust-based to policy-enforced governance.
How Organizations Use OAuth Custom Scopes
- CloudServe Shipping — CloudServe creates a custom scope called 'read_orders' that grants read-only access to Order and Order Item objects. Their third-party shipping integration requests only this scope during authentication. Even though the integration authenticates with a user who has broad Salesforce access, the custom scope restricts the API session to Order data only, preventing any access to Contacts or Opportunities.
- DataBridge Analytics — DataBridge defines custom scopes for their three analytics integrations: 'read_pipeline' for sales analytics, 'read_cases' for service analytics, and 'read_marketing' for campaign analytics. Each integration requests only its relevant scope. When the security team audits API access, they can see exactly which data each analytics tool can reach without reviewing complex profile permissions.
- SecureHealth Patient Portal — SecureHealth creates a custom scope called 'patient_read' that limits their patient-facing portal to reading only Patient__c and Appointment__c custom objects. The HIPAA compliance team requires documentation showing that the portal cannot access billing or clinical notes objects. The custom scope definition serves as auditable proof of data access boundaries.