---
schema_version: "1"
id: 96a735e428890a9a3b8264b29057427806c860341447bc7e0a5210d8180ede3e
title: OAuth 2.0 Username-Password Flow for Special Scenarios
collection: admin
version: current
locale: en-us
portal_url: https://docs.salesforce.com/admin/current/en-us/xcloud/264-0-0/remoteaccess_oauth_username_password_flow.md
canonical_url: https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_username_password_flow.htm&release=264.0.0&type=5
source_site: help.salesforce.com
content_type: documentation
content_hash: a9bdfc711920f216fdb9841cc02de5abd48fcf978e2a614466df2300de824f59
description: You can use the username-password flow to authorize a client via a connected app that already has the user’s credentials. However, we recommend avoiding this flow because it passes credentials back and forth. Use it only if there’s a high degree of trust between the resource owner and the client, the client is a first-party app, Salesforce is hosting the data, and other grant types aren’t available. In these cases, set user permissions to minimize access and protect stored credentials from unauthorized access.
products:
  - Security
  - Cross Cloud
release: "264"
---
# OAuth 2.0 Username-Password Flow for Special Scenarios

You can use the username-password flow to authorize a client via a connected app that already has the user’s credentials. However, we recommend avoiding this flow because it passes credentials back and forth. Use it only if there’s a high degree of trust between the resource owner and the client, the client is a first-party app, Salesforce is hosting the data, and other grant types aren’t available. In these cases, set user permissions to minimize access and protect stored credentials from unauthorized access.

### Required Editions

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small edition"><colgroup><col></colgroup><tbody><tr class=""><td class="slds-cell-wrap" style="vertical-align:top;">Available in: both Salesforce Classic and Lightning Experience</td></tr><tr class=""><td class="slds-cell-wrap" style="vertical-align:top;">Available in: <strong>All</strong> Editions</td></tr></tbody></table>

![Important](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-identity-264-0-0-production-enus/699dab6f-8f1a-4662-b24f-6521d5b747f7/images/icon_important.png)

Important For increased security, we recommend using the OAuth 2.0 web server flow with Proof Key for Code Exchange (PKCE) or the OAuth 2.0 client credentials flow instead of the username-password flow. We also recommend that you block all connected apps from using the username-password flow. For steps to use the web server flow, see [OAuth 2.0 Web Server Flow for Web App Integration](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_web_server_flow.htm&release=264.0.0&type=5 "To integrate an external web app with the Salesforce API, use the OAuth 2.0 web server flow, which implements the OAuth 2.0 authorization code grant type. With this flow, the server hosting the web app must be able to protect the external client app’s identity, defined by the client ID and client secret."). For steps to use the client credentials flow, see [OAuth 2.0 Client Credentials Flow for Server-to-Server Integration](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_client_credentials_flow.htm&release=264.0.0&type=5 "Sometimes you want to directly share information between two applications without a user getting in the way. For these scenarios, you can use the OAuth 2.0 client credentials flow. In this flow, the client app exchanges its client credentials defined in the external client app—its consumer key and consumer secret—for an access token. This flow eliminates the need for explicit user interaction, though it does require you to specify an integration user to run the integration. You can use this flow as a more secure alternative to the OAuth 2.0 username-password flow."). For steps to block the username-password flow, see [Block Authorization Flows to Improve Security](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_disable_username_password_flow.htm&release=264.0.0&type=5 "The OAuth 2.0 user-agent and username-password flows are considered insecure and aren’t recommended. For better security, we strongly recommend that you block these flows in Salesforce to prevent developers from using them to build new integrations. If your org is created in Summer ‘23 or later, the username-password flow is blocked by default. You can enable the username-password flow if needed. If you have existing integrations that use the user-agent or username-password flow, update them to a more secure OAuth 2.0 flow. You can also block the Authorization Code and Credentials Flow, which is used to securely configure a headless login process. And you can block certain flows that don’t use the PKCE extension.").

The username-password flow generates access tokens as Salesforce Session IDs that can’t be introspected. Because the access tokens are temporary, connected apps that are using this flow aren’t displayed on the Connected Apps OAuth Usage page, even if they have an active session. This flow doesn’t support scopes or refresh tokens. Experience Cloud sites don’t support the OAuth 2.0 username-password flow.

Here are the major steps involved in the username-password flow.

- The connected app [requests an access token](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_username_password_flow.htm&release=264.0.0&type=5) by sending the user’s login credentials to the Salesforce token endpoint.
- After verifying the request, Salesforce [grants an access token](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_username_password_flow.htm&release=264.0.0&type=5) to the connected app.
- The connected app can [use the access token](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_tokens_scopes.htm&release=264.0.0&type=5) to access the protected data on the user’s behalf.

## Request an Access Token

To request an access token, the connected app sends the user’s username and password as an out-of-band POST to the Salesforce token endpoint. This POST is an example.

```
grant_type=password&
client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&
client_secret=1955279925675241571&
username=testuser@salesforce.com&
password=mypassword
```

Include these credentials in the POST.

![Important](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-identity-264-0-0-production-enus/699dab6f-8f1a-4662-b24f-6521d5b747f7/images/icon_important.png)

Important When developing OAuth integrations, always pass sensitive information in the body of a POST request or in a request header. Don't use GET parameters in the URL query string to pass sensitive information. Sensitive information includes but isn't limited to usernames, passwords, OAuth tokens, client secrets, and any personally identifiable information. For more information on security best practices, see [Storing Sensitive Data](https://developer.salesforce.com/docs/atlas.en-us.secure_coding_guide.meta/secure_coding_guide/secure_coding_storing_sensitive_data.htm) in the Secure Coding Guide.

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small ">
        <colgroup>
          <col>
          <col>
        </colgroup>
        <thead class="slds-text-title_caps ">
          <tr class="">
            <th scope="col" class="slds-cell-wrap" style="vertical-align:top;" id="d27293e153">Parameter</th>
            <th scope="col" class="slds-cell-wrap" style="vertical-align:top;" id="d27293e156">Description</th>
          </tr>
        </thead>
        <tbody>
          <tr class="">
            <td data-label="Parameter" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e153 ">
              <code>grant_type</code>
            </td>

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e156 ">The OAuth 2.0 grant type that the connected app requests. The value must be
              <code>password</code> for this flow.
            </td>

          </tr>
          <tr class="">
            <td data-label="Parameter" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e153 ">
              <code>client_id</code>
            </td>

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e156 ">The consumer key of the connected app. To access the consumer key, from the App
              Manager, find the connected app and select <strong class="uicontrol">View</strong> from the
              dropdown. Then click <strong class="uicontrol">Manage Consumer Details</strong>. You're
              sometimes prompted to verify your identity before you can view the consumer
              key.</td>

          </tr>
          <tr class="">
            <td data-label="Parameter" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e153 ">
              <code>client_secret</code>
            </td>

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e156 ">
              <span>The consumer secret of the connected app. To access the consumer secret,
                from the App Manager, find the connected app and select
                <strong class="uicontrol">View</strong> from the dropdown. Then click <strong class="uicontrol">Manage
                  Consumer Details</strong>. You're sometimes prompted to verify your identity
                before you can view the consumer secret.</span>
            </td>

          </tr>
          <tr class="">
            <td data-label="Parameter" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e153 ">
              <code>username</code>
            </td>

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e156 ">The username of the user that the connected app is imitating.</td>

          </tr>
          <tr class="">
            <td data-label="Parameter" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e153 ">
              <code>password</code>
            </td>

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e156 ">
              <p>The password of the user that the connected app is imitating. </p>
              <p style="margin-bottom:0;">When using the
                username-password flow with an API, create a field in the username and password
                login screen where users can enter their security token. The security token is an
                automatically generated key that must be added to the end of the password to log
                in to Salesforce from an untrusted network. Concatenate the password and token
                when passing the request for authentication.</p>
            </td>

          </tr>
          <tr class="">
            <td data-label="Parameter" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e153 ">
              <code>format</code>
            </td>

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d27293e156 ">
              <p>If not included in the request’s header, you can specify the expected return
                format. The <code>format</code> parameter takes precedence
                over the request’s header. These formats are supported.</p>
              <ul>
                <li><code>urlencoded</code></li>
                <li><code>json</code> (default)</li>
                <li><code>xml</code></li>
              </ul>
            </td>

          </tr>
        </tbody>
      </table>

## Salesforce Grants an Access Token

After the request is verified, Salesforce sends a response to the client.

Here’s an example response.

```
{"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448832702",
"instance_url":"https://yourInstance.salesforce.com/",
"signature":"0CmxinZir53Yex7nE0TD+zMpvIWYGb/bdJh6XfOH6EQ=",
"access_token":"00Dx0000000BV7z!AR8AQAxo9UfVkh8AlV0Gomt9Czx9LjHnSSpwBMmbRcgKFmxOtvxjTrKW19ye6PE3Ds1eQz3z8jr3W7_VbWmEu4Q8TVGSTHxs",
"token_type":"Bearer"}
```

These parameters are in the body of the response.

 
| Parameter | Description |
| --- | --- |
| `id` | An identity URL that can be used to identify the user and to query for more information about the user. See [Identity URLs](https://help.salesforce.com/articleView?id=remoteaccess_using_openid.htm&language=en_US). |
| `issued_at` | Time stamp of when the signature was created in milliseconds. |
| `instance_url` | A URL indicating the instance of the user’s org. For example: `https://yourInstance.salesforce.com/`. |
| `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. |
| `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. |
| `token_type` | A `Bearer` token type, which is used for all responses that include an access token. |

![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-identity-264-0-0-production-enus/699dab6f-8f1a-4662-b24f-6521d5b747f7/images/icon_note.png)

Note This response doesn’t send a refresh token.

#### See Also

- [OAuth 2.0 Authorization Errors](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_flow_errors.htm&release=264.0.0&type=5 "Errors can occur during OAuth authorization. For example, a user denies access to the connected app or request parameters are incorrect. When errors occur, the authorizing server sends an error to the callback URL with an error code.")