Scope Parameter Values

OAuth requires scope configuration both on server and on client. The agreement between the two sides defines the scope contract.

  • Server side - Define scope permissions in an external client app or connected app on the Salesforce server. These settings determine which levels of access client apps, such as Mobile SDK apps, can request. At a minimum, configure your external client app or connected app OAuth settings to match what is specified in your code. For most apps, refresh_token, web, and api are sufficient.
  • Client side - Specify scope requests in your Mobile SDK app. Client scope requests must be a subset of the external client app or connected app’s scope permissions. Starting in Mobile SDK 13.2, apps no longer need to define OAuth scopes in the boot config. When scopes are not specified, users are granted all configured scopes from the external client app or connected app. These default-scope clients rely entirely on server-side configuration to determine access levels. The granted scopes are automatically captured by the SDK, saved with user account credentials, and available to query in application logic.

Server Side Configuration 

You can set the following scope parameter values.

ValueDescription
Perform ANSI SQL queries on Customer Data Platform data (cdp_query_api)Allows ANSI SQL queries of Data Cloud data on behalf of the user.
Manage Pardot services (pardot_api)Allows access to Marketing Cloud Account Engagement API services on behalf of the user. Manage the full extent of accessible services in Account Engagement. (Pardot is now Marketing Cloud Account Engagement.)
Manage Customer Data Platform profile data (cdp_profile_api)Allows access to Data Cloud REST API data. Use this scope to manage profile records.
Access Connect REST API resources (chatter_api)Allows access to Connect REST API resources on behalf of the user.
Manage Customer Data Platform Ingestion API data (cdp_ingest_api)Allows access to Data Cloud Ingestion API data. Use this scope to upload and maintain external datasets in Data Cloud. This scope is packaged in a JSON web token (JWT).
Access Analytics REST API Charts Geodata resources (eclair_api)Allows access to the Analytics REST API Charts Geodata resource.
Access Analytics REST API resources (wave_api)Allows access to the Analytics REST API resources.
Manage user data via APIs (api)Allows access to the current, logged-in user’s account using APIs, such as REST API and Bulk API 2.0. This scope also includes chatter_api, which allows access to Connect REST API resources.
Access custom permissions (custom_permissions)Allows access to the custom permissions in an org associated with an external client app or connected app. This scope also shows whether the current user has each permission enabled.
Access the identity URL service (id, profile, email, address, phone)Allows access to the identity URL service. You can request profile, email, address, or phone individually to get the same result as using id because they’re synonymous.
Access Lightning applications (lightning)Allows hybrid apps to directly obtain Lightning child sessions through the OAuth 2.0 hybrid app token flow and hybrid app refresh token flow.
Access content resources (content)Allows hybrid apps to directly obtain content child sessions through the OAuth 2.0 hybrid app token flow and hybrid app refresh token flow.
Access unique user identifiers (openid)Allows access to the current, logged in user’s unique identifier for OpenID Connect apps.In the OAuth 2.0 user-agent flow and the OAuth 2.0 web server flow, use the openid scope. In addition to the access token, this scope enables you to receive a signed ID token that conforms to the OpenID Connect specifications.
Full access (full)Allows access to all data accessible by the logged-in user, and encompasses all other scopes.full doesn’t return a refresh token. You must explicitly request the refresh_token scope to get a refresh token.
Perform requests at any time (refresh_token, offline_access)Allows a refresh token to be returned when the requesting client is eligible to receive one. With a refresh token, the app can interact with the user’s data while the user is offline. This token is synonymous with requesting offline_access.
Access Visualforce applications (visualforce)Allows access to customer-created Visualforce pages only. This scope doesn’t allow access to standard Salesforce UIs.To allow hybrid apps to directly obtain Visualforce child sessions, include this scope with the OAuth 2.0 hybrid app token flow or hybrid app refresh token flow.
Manage user data via Web browsers (web)Allows use of the access_token on the web. This scope also includes visualforce, allowing access to customer-created Visualforce pages.
Access chatbot services (chatbot_api)Allows access to Einstein Bot API services.
Access Headless Registration API (user_registration_api)Allows access to the API for the Headless Registration Flow. If you set up your flow to require authentication, you must pass in an access token that includes this scope.
Access Headless Forgot Password API (forgot_password)Allows access to the API for the Headless Forgot Password Flow. If you set up your flow to require authentication, you must pass in an access token that includes this scope.
Access all Data Cloud API resources (cdp_api)Allows access to all Data Cloud API resources.
Access the Salesforce API Platform (sfap_api)Reserved for future use.
Access Interaction API resources (interaction_api)Reserved for future use.

For Mobile SDK apps, you’re always required to select refresh_token in server-side Connected App settings. Even if you select the full scope, you still must explicitly select refresh_token.

Note

Client Side Configuration 

The following rules govern scope configuration for Mobile SDK apps.

ScopeMobile SDK App Configuration
refresh_tokenImplicitly requested by Mobile SDK for your app; no need to include in your app’s list of scopes.
apiInclude if you’re  making any Salesforce REST API calls (applies to most apps).
webInclude if your app accesses pages defined in a Salesforce org (for any app that loads Salesforce-based web pages.)
fullInclude to request all permissions. (Mobile SDK implicitly requests refresh_token for you.)
chatter_apiInclude if your app calls Connect REST APIs.
id(Not needed)
visualforceUse web instead.

Android APIs for Dynamic Scope Retrieval 

Starting in Mobile SDK 13.2, the UserAccount class stores and exposes the OAuth scopes granted during authentication.

Java 

1import com.salesforce.androidsdk.accounts.UserAccount;
2import com.salesforce.androidsdk.accounts.UserAccountManager;
3import java.util.List;
4
5// Get the current user's granted scopes.
6UserAccount currentUser = UserAccountManager.getInstance().getCurrentUser();
7List<String> grantedScopes = currentUser.getScope(); // Returns list of scope strings.
8
9// Example: Check if a specific scope was granted.
10if (grantedScopes != null && grantedScopes.contains("sfap_api")) {
11    Log.d(TAG, "User has sfap_api scope");
12}

Kotlin 

1import com.salesforce.androidsdk.accounts.UserAccount
2import com.salesforce.androidsdk.accounts.UserAccountManager
3
4// Get the current user's granted scopes.
5val currentUser = UserAccountManager.getInstance().currentUser
6val grantedScopes = currentUser?.scope // Returns List<String>?
7
8// Example: Check if a specific scope was granted.
9grantedScopes?.let { scopes ->
10    if ("sfap_api" in scopes) {
11        Log.d(TAG, "User has sfap_api scope")
12    }
13}

Starting in Mobile SDK 13.2, the OAuthConfig class allows scopes to be null.

Kotlin 

1import com.salesforce.androidsdk.config.OAuthConfig
2
3// Create config with no scopes (request all available).
4val config = OAuthConfig(
5    consumerKey = "your_consumer_key",
6    redirectUri = "your_redirect_uri",
7    scopes = null // Grants all scopes from the external client app or connected app.
8)
9
10// Create config with specific scopes.
11val configWithScopes = OAuthConfig(
12    consumerKey = "your_consumer_key",
13    redirectUri = "your_redirect_uri",
14    scopes = listOf("api", "refresh_token", "id")
15)

iOS APIs for Dynamic Scope Retrieval 

Starting in Mobile SDK 13.2, the SFOAuthCredentials class exposes granted OAuth scopes.

Objective-C 

1#import <SalesforceSDKCore/SFOAuthCredentials.h>
2#import <SalesforceSDKCore/SFUserAccountManager.h>
3
4// Get the current user's granted scopes.
5SFUserAccount *currentUser = [SFUserAccountManager sharedInstance].currentUser;
6NSArray<NSString *> *grantedScopes = currentUser.credentials.scopes;
7
8// Example: Check if a specific scope was granted.
9if (grantedScopes && [grantedScopes containsObject:@"sfap_api"]) {
10    NSLog(@"User has sfap_api scope");
11}

Swift 

1import SalesforceSDKCore
2
3// Get the current user's granted scopes.
4if let currentUser = UserAccountManager.shared.currentUserAccount {
5    let grantedScopes = currentUser.credentials.scopes
6
7    // Example: Check if a specific scope was granted.
8    if let scopes = grantedScopes, scopes.contains("sfap_api") {
9        print("User has sfap_api scope")
10    }
11}

Starting in Mobile SDK 13.2, SFSDKAppConfig (BootConfig in Swift) allows scopes to be optional.

Objective-C 

1#import <SalesforceSDKCore/SFSDKAppConfig.h>
2
3// Create config with no scopes (request all available).
4NSDictionary *configDict = @{
5    @"remoteAccessConsumerKey": @"your_consumer_key",
6    @"oauthRedirectURI": @"your_redirect_uri",
7    @"shouldAuthenticate": @YES
8    // No oauthScopes key; requests all available scopes.
9};
10
11SFSDKAppConfig *config = [[SFSDKAppConfig alloc] initWithDict:configDict];

Swift 

1import SalesforceSDKCore
2
3// Create config with no scopes (request all available).
4let configDict: [String: Any] = [
5    "remoteAccessConsumerKey": "your_consumer_key",
6    "oauthRedirectURI": "your_redirect_uri",
7    "shouldAuthenticate": true
8    // No oauthScopes key; requests all available scopes.
9]
10
11if let config = BootConfig(configDict) {
12    // Use config for authentication.
13}

AuthFlowTester Examples 

To display granted scopes to users, see these examples from the AuthFlowTester sample app.

Android (Kotlin) 

1// From AuthFlowTesterActivity.kt
2@Composable
3fun UserCredentialsView(user: UserAccount?) {
4    user?.let { account ->
5        // Display granted scopes.
6        account.scope?.let { scopes ->
7            InfoSection(title = "Granted Scopes") {
8                Text(
9                    text = scopes.joinToString(separator = ", "),
10                    style = MaterialTheme.typography.bodyMedium
11                )
12            }
13        }
14    }
15}

iOS (Swift) 

1// From SessionDetailViewController.swift
2struct UserCredentialsView: View {
3    var body: some View {
4        if let credentials = UserAccountManager.shared.currentUserAccount?.credentials {
5            // Display granted scopes.
6            if let scopes = credentials.scopes {
7                InfoSection(title: "Granted Scopes") {
8                    Text(scopes.joined(separator: ", "))
9                }
10            }
11        }
12    }
13}

We've Moved

Welcome to the new home of the Mobile SDK Developer Guide! For now, the Japanese guide can be found in PDF form.