---
schema_version: "1"
id: f4fdff52d04582c652b1d88be897641c693dc2bfe097b80ae0c0b51eb83c995e
title: SAML Assertion Flow for Accessing the API
collection: admin
version: current
locale: en-us
portal_url: https://docs.salesforce.com/admin/current/en-us/xcloud/264-0-0/remoteaccess_oauth_web_sso_flow.md
canonical_url: https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_web_sso_flow.htm&release=264.0.0&type=5
source_site: help.salesforce.com
content_type: documentation
content_hash: e8e4375efaeb2c3918c73762e43ecef050b06be02cab51e0eaac46113b431707
description: The SAML assertion flow is an alternative for orgs that use SAML to access Salesforce and want to access the API the same way. Clients can federate with the API using a SAML assertion, the same way they federate with Salesforce for Web Single Sign-On (Web SSO). You can use this assertion flow without a connected app.
products:
  - Security
  - Cross Cloud
release: "264"
---
# SAML Assertion Flow for Accessing the API

The SAML assertion flow is an alternative for orgs that use SAML to access Salesforce and want to access the API the same way. Clients can federate with the API using a SAML assertion, the same way they federate with Salesforce for Web Single Sign-On (Web SSO). You can use this assertion flow without a connected app.

### 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>

Review these limitations:

- You can’t use this flow with more than one org.
- Authentication through this flow doesn’t invoke login flows. You can’t apply login flows to API logins or to scenarios in which sessions pass to the UI through frontdoor.jsp from a non-UI login process.
- Experience Cloud sites don’t support this flow.

To use the SAML assertion flow, follow these steps.

1. Configure SAML version 2.0 for your org.
2. Exchange a SAML assertion for an access token.
3. After verifying the assertion, Salesforce grants an access token.
4. Use a JSON parser to process the response and extract the 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 A `refresh_token` is never issued in this flow.

## Configure SAML 2.0

To configure your org to use SAML, see [Configure SSO with Salesforce as a SAML Service Provider](https://help.salesforce.com/articleView?id=sso_saml.htm&language=en_US). You can use the same configuration for web and API federation.

After you configure SAML, Salesforce generates these URLs.

- Salesforce.com Login URL—Use this URL with Web SSO.
- OAuth 2.0 Token Endpoint—Use this URL when exchanging a SAML assertion for an access token to access the API.

When generating SAML assertions to use with the Salesforce token endpoint, the recipient URL in the assertion can be the value from the OAuth 2.0 Token Endpoint or the Salesforce.com Login URL.

## Exchange a SAML Assertion for an Access Token

To exchange a SAML assertion for an access token, your client obtains or generates a valid SAML response, and then posts it to the Salesforce token endpoint. The client determines the method for obtaining this response.

Here’s an example of an out-of-band POST made to the Salesforce token endpoint.

```
grant_type=assertion&
assertion_type=urn:oasis:names:tc:SAML:2.0:profiles:SSO:browser&
assertion=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHNhbW. . .
```

When the client receives a valid response, it sends these parameters.

![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="d17721e167">Parameter</th>
            <th scope="col" class="slds-cell-wrap" style="vertical-align:top;" id="d17721e170">Description</th>
          </tr>
        </thead>
        <tbody>
          <tr class="">
            <td data-label="Parameter" class="slds-cell-wrap" style="vertical-align:top;" headers="d17721e167 ">
              <code>grant_type</code>
            </td>

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

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

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d17721e170 ">A Base-64 encoded, then URL encoded, SAML response normally used for Web
              SSO.</td>

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

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d17721e170 ">The value must be <code>urn:oasis:names:tc:SAML:2.0:profiles:SSO:browser</code>, URL encoded.</td>

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

            <td data-label="Description" class="slds-cell-wrap" style="vertical-align:top;" headers="d17721e170 ">
              <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 SAML response is verified, Salesforce sends a response to the client containing the access token.

Here’s an example response from Salesforce.

```
{"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"instance_url":"https://yourInstance.salesforce.com",
"access_token":"00Dx0000000BV7z!AR8AQNhMmQeDIKR0.hZagSTaEPCkmoXeYnkaxQnqWlG6Sk9U3i3IFjEHIzDlsYdU0qoVCXNJtPOwdb7u5rKfq9NldfAKoQjd",
"token_type":"Bearer"} 
```

 
| 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). |
| `instance_url` | A URL indicating the instance of the user’s org. For example: `https://yourInstance.salesforce.com/`. |
| `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. |

#### See Also

- [Single Sign-On](https://help.salesforce.com/s/articleView?id=xcloud.sso_about.htm&type=5&language=en_US)
- [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.")