OAuth 2.0 User-Agent Flow for Desktop or Mobile App Integration
With the OAuth 2.0 user-agent flow, users authorize a desktop or mobile app to access data by using an external or embedded browser. Client apps running in a browser using a scripting language such as JavaScript can also use this flow. This flow uses the OAuth 2.0 implicit grant type.
Required Editions
| Available in: both Salesforce Classic and Lightning Experience |
| Available in: All Editions |
See New connected apps can no longer be created in Spring ‘26 for more details.
With the user-agent flow, the connected app, which integrates the client app with the Salesforce API, receives the access token as an HTTP redirection. The connected app requests that the authorization server redirects the user-agent to a web server or to an accessible local resource. The web server can extract the access token from the response and pass it to the connected app. For security, the token response is provided as a hash tag (#) fragment on the URL. This format prevents the token from being passed to the server or to any other servers in referral headers.
For example, you use Salesforce Mobile SDK to build a mobile app that looks up customer contact information from your Salesforce org. Mobile SDK implements the OAuth 2.0 user-agent flow for your connected app, integrating the mobile app with your Salesforce API and giving it authorized access to the defined data. The flow follows these steps.
- The user opens the mobile app.
- The connected app directs the user to Salesforce to authenticate and authorize the mobile app.
- The user approves access for this authorization flow.
- The connected app receives the callback from Salesforce to the redirect URL, which extracts the access and refresh tokens.
- The connected app uses the access token to access data on the user’s behalf.
Redirection to Authorization Endpoint
To get a user’s authorization to access Salesforce data, the connected app redirects the user to the authorization endpoint. Here’s an example HTTP redirection.
https://login.salesforce.com/services/oauth2/authorize?response_type=token&
client_id=3MVG9lKcPoNINVBIPJjdw1J9LLJbP_pqwoJYyuisjQhr_LLurNDv7AgQvDTZwCoZuDZrXcPCmBv4o.8ds.5iE&
redirect_uri=https://www.customercontactinfo.com/user_callback.jspk&
state=mystateInclude these parameters in the URL.
| Parameter | Description |
|---|---|
| OAuth 2.0 authorization endpoint | The Salesforce instance’s OAuth 2.0 authorization endpoint. Connected apps send OAuth authorization requests to this endpoint. |
client_id
|
The consumer key of the connected app. To access the consumer key, from the App Manager, find the connected app and select View from the dropdown. Then click Manage Consumer Details. You're sometimes prompted to verify your identity before you can view the consumer key. |
redirect_uri
|
The URL where users are redirected after a successful authentication. The redirect URI must match one of the values in the connected app’s Callback URL field. Otherwise, the approval fails. You can find the redirect URI on the connected app’s Manage Connected Apps page or from the connected app’s definition. This value must be URL encoded. |
response_type
|
Use the token value. You can also use the token
id_token value, with the openid scope and a
nonce parameter. If you specify token id_token,
Salesforce returns an ID token in the response. |
These parameters are optional.
| Parameter | Description |
|---|---|
scope
|
Permissions that define the type of protected resources a 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. If you don’t include this parameter, all scopes assigned to the connected app are requested. The scopes passed in this parameter must be a subset of the registered scopes. For valid parameters, see OAuth Scopes. |
state
|
Any state that the external web service requests to be sent to the callback URL. This value must be URL encoded. |
display
|
Changes the display type of the login and authorization pages. Salesforce supports these values.
|
login_hint
|
Provides a valid username value to prepopulate the login page with the
username, such as To pass the
|
nonce
|
Use with the openid scope to request a user ID token. The user
ID token is returned in the response. This parameter is optional, but it helps to
detect replay attacks.
|
prompt
|
Specifies how the authorization server prompts the user for reauthentication and reapproval. Salesforce supports these values.
You can pass |
prompt
|
Specifies how the authorization server prompts the user for reauthentication and reapproval. Salesforce supports these values.
You can pass |
sso_provider
|
The developer name of a single sign-on (SSO) identity provider configured with a My Domain login URL or Experience Cloud site URL. You can use this parameter to create an SSO experience that feels like your app is integrated with the SSO provider. For example, you can use this parameter to offer SSO in a Headless Identity implementation. |
User Authenticates and Authorizes Access
The user logs into Salesforce with their credentials. The user interacts with the authorization endpoint directly, so the application never sees the user’s credentials.
After a successful login, Salesforce redirects users to the approval page to grant access to the app.
Salesforce Grants Access Token
After a user approves access to a connected app, Salesforce redirects the user to the callback URL. Included in the redirection is the granted access token, which the connected app can extract and use to access data on the user’s behalf.
Here’s an example of the callback from the server. The response is behind a hash tag (#), rather than as HTTP query parameters.
https://www.customercontactinfo.com/user_callback.jsp#
access_token=00Dx0000000BV7z%21AR8AQBM8J_xr9kLqmZIRyQxZgLcM4HVi41aGtW0qW3JCzf5xd
TGGGSoVim8FfJkZEqxbjaFbberKGk8v8AnYrvChG4qJbQo8&
refresh_token=5Aep8614iLM.Dq661ePDmPEgaAW9Oh_L3JKkDpB4xReb54_pZfVti1dPEk8aimw4Hr9ne7VXXVSIQ%3D%3D&
instance_url=https://yourInstance.salesforce.com&
id=https://login.salesforce.com%2Fid%2F00Dx0000000BV7z%2F005x00000012Q9P&
issued_at=1278448101416&
signature=miQQ1J4sdMPiduBsvyRYPCDozqhe43KRc1i9LmZHR70%3D&
scope=id+api+refresh_token&
token_type=Bearer&
state=mystateThe response in the example contains these parameters following the hash tag (#). The connected app’s callback URL precedes the hash tag (#).
| Parameter | Description |
|---|---|
access_token
|
OAuth token that a connected app uses to request access to a protected resource on behalf of the client application. Additional permissions in the form of scopes can accompany the access token. |
refresh_token
|
Token obtained from the web server, user-agent, or hybrid app token flow. This value is a secret. Take appropriate measures to protect it. The refresh token for
the user-agent flow is only issued if you requested
|
instance_url
|
A URL indicating the instance of the user’s org. For example:
https://yourInstance.salesforce.com/. |
id
|
An identity URL that can be used to identify the user and to query for more information about the user. See Identity URLs. |
issued_at
|
Time stamp of when the signature was created in milliseconds. |
signature
|
Base64-encoded HMAC-SHA256 signature signed with the
client_secret. The signature can include the concatenated ID and
issued_at value, which you can use to verify that the identity
URL hasn’t changed since the server sent it. |
scope
|
The scopes associated with the access token. Scopes further define the type of protected resources that the client 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. For valid parameters, see OAuth Scopes. |
token_type
|
A Bearer token type, which is used for all responses that
include an access token. |
state
|
The state requested by the client. This value is included only if the
state parameter is included in the original query string. |
The response can also contain these parameters.
| Parameter | Description |
|---|---|
id_token
|
A signed data structure that contains authenticated user attributes, including a unique identifier for the user and a timestamp indicating when the token was issued. It also identifies the requesting client app. See OpenID Connect specifications. This parameter is returned if the
scope parameter includes
|
sfdc_site_url
|
If the user is a member of an Experience Cloud site, the site URL is provided. |
sfdc_site_id
|
If the user is a member of an Experience Cloud site, the user’s site ID is provided. |
