Loading
Salesforce now sends email only from verified domains. Read More
Identify Your Users and Manage Access
Table of Contents
Filter by (0)Add
Select Filters

          No results
          No results
          Here are some search tips

          Check the spelling of your keywords.
          Use more general search terms.
          Select fewer filters to broaden your search.

            Search all of Salesforce Help
            Search all of Salesforce Help
            OAuth Tokens and Scopes

            You are here:

            1. Salesforce Help
            2. Docs
            3. Identify Your Users and Manage Access

            OAuth Tokens and Scopes

            OAuth tokens authorize access to protected resources. Connected apps receive tokens on behalf of a client after authorization. Scopes further define the type of protected resources that the connected app can access. You assign scopes to a connected app when you build it, and they’re included with the OAuth tokens during the authorization flow.

            Required Editions

            Available in: both Salesforce Classic and Lightning Experience
            Available in: All Editions

            OAuth Tokens

            Depending on the authorization flow, the authorizing server can provide these OAuth tokens to the client.

            OAuth Token Description
            Authorization code The authorization server creates an authorization code, which is a short-lived token, and passes it to the client after successful authentication. The client sends the authorization code to the authorization server to obtain an access token and, optionally, a refresh token.
            Access token

            After a client is authorized, Salesforce sends the client an access token. The client passes the access token to the resource server to request access to protected resources. The resource server validates the access token and additional permissions in the form of scopes before granting access to the client.

            The access token has a longer lifetime than the authorization code, usually minutes or hours. When an access token expires, attempts to use it fail. The client must obtain a new access token by using a refresh token or reinitiating the authorization flow.

            The client must be able to protect the access token against interception by a protocol such as Transport Layer Security (TLS or SSL).

            To implement an OAuth 2.0 authorization flow that uses an access token, assign the web scope to the connected app that is integrating the client with the Salesforce API.

            After receiving an access token, the client can use one of these methods to request access.

            • For REST API, use an HTTP authorization header with this format: Authorization: Bearer Access_Token.
            • For SOAP API, use the SessionHeader SOAP authorization header. The access token is placed in the header.
            • For the identity URL, use either an HTTP authorization header (as with REST API) or an HTTP parameter oauth_token.

            Salesforce grants unique access tokens for each connected app (client) and user combination. But it’s possible for Salesforce to issue the same access token to different service providers under these conditions:

            • You configure a single connected app for multiple service providers.
            • A user has an active session with one service provider. The user then logs in to a different service provider by using the same connected app that was configured for both service providers.

            To make sure that different service providers receive unique access tokens, create a distinct connected app for each service provider.
            Refresh token

            A client can use a refresh token repeatedly to gain access to the resource server. When a refresh token expires or a user revokes it outside of the client, the client requests a new access token, typically by implementing the authorization flow from the start.

            A refresh token can have an indefinite lifetime, persisting for an admin-configured interval or until explicitly revoked. The client can store a refresh token and use it to obtain new access tokens. For security, the client must protect a refresh token against unauthorized access.

            If the request includes the refresh_token or offline_access scope, the OAuth 2.0 user-agent and the OAuth 2.0 web server flows can request refresh tokens.
            ID token

            The ID token is a signed data structure that contains authenticated user attributes, including a unique identifier for the user and when the token was issued. It also identifies the requesting client app. Salesforce can respond to an OAuth request with an ID token that conforms to the OpenID Connect specifications.

            If the request includes these parameters, both the OAuth 2.0 user-agent and OAuth 2.0 web server flows can request a signed ID token. The returned token is a JSON web token (JWT).

            • The user-agent flow must include the response_type parameter with the token id_token value, the openid scope, and the nonce parameter.
            • The web server flow must include the response_type parameter with the code value, and the openid scope. The nonce parameter is optional.

            Here’s an example request for an ID token by using the user-agent flow.

            https://MyDomainname.my.salesforce.com/services/oauth2/authorize?response_type=token+id_token
&redirect_uri=https://MyDomainName.my.salesforce.com/services/oauth2/success
&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLJbP_pqwoJYyuisjQhr_LLurNDv7AgQvDTZwCoZuD_
3Oxug0sU3_WrBPd_Ax6Mcnlg5HSnLGQ&scope=openid&nonce=somevalue

            Use the published public keys to verify that the signature in the response is a valid Salesforce signature. On MyDomainName.my.salesforce.com/id/keys, the response includes JSON-formatted information about the public keys used for signing. Validate the signature by using the key with the correct kid value, which specifies the release version.
            Initial access token Salesforce requires an initial access token to authorize the dynamic client registration request flow. After configuring an OAuth 2.0 connected app, generate an initial access token.
            Asset token For efficient token exchange and automatic linking of devices to Service Cloud Asset data, a client can implement the OAuth 2.0 device flow. In this flow, the client can exchange an access token and an actor token for an asset token. This flow combines asset token issuance and asset registration.
            Delete token A token that can be used to revoke refresh tokens and associated access tokens. This token is represented by the DeleteToken field on the OauthToken object. To use this token, include it in a request to the OAuth 2.0 revocation endpoint, or use Apex. See Revoke Opaque OAuth Tokens.

            OAuth Scopes

            You can assign these OAuth scopes to the connected app to define the type of protected resources that the client can access.

            Value Description
            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 some Connect REST API resources on behalf of the user. To allow access to all Connect REST API resources, use the api scope.
            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 by using APIs, such as REST API and Bulk API 2.0. This scope also allows access to all Connect REST API resources.
            Access custom permissions (custom_permissions) Allows access to the custom permissions in an org associated with the 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 by 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) Allows access to the Salesforce API Platform, including API services accessed from api.salesforce.com or the equivalent operating zone endpoint.
            Access Interaction API resources (interaction_api) Reserved for future use.

            When the client receives an access token, the authorizing server also includes the scopes assigned to the connected app in its response. These scopes are also stored with the refresh token. For JSON or SAML bearer token requests, the request combines the scopes of all previous refresh tokens.

            All scope values include id, which you can use to access the identity URLs at any time.

            This example request includes the api, id, and web scopes. The scope values are separated with the space character, %20.

            https://MyDomainName.my.salesforce.com/services/oauth2/authorize?
response_type=token&
client_id=3MVG9lKcPoNINVBKV6EgVJiF.snSDwh6_2wSS7BrOhHGEJkC_&
redirect_uri=http%3A%2F%2F2www.example.org%2Fqa%2Fsecurity%2Foauth%2Fuseragent_flow_callback.jsp&
scope=api%20id%20web
             
            Loading
            Salesforce Help | Article