OAuth 2.0 Client Credentials Flow for Server-to-Server Integration

Request an Access Token

Let’s break down the process of getting an access token with the client credentials flow.

To initiate the flow, the external client app posts its client credentials to the Salesforce token endpoint. You can include the client credentials as parameters in the body of the request. Or, for added security, put your client credentials in a Basic authorization header.

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 in the Secure Coding Guide.

Here’s an example POST request with the client credentials in the request body.

POST /services/oauth2/token HTTP/1.1
Host: MyDomainName.my.salesforce.com
grant_type=client_credentials&
client_id=*******************&
client_secret=*******************

For this flow, requests to https://login.salesforce.com and https://test.salesforce.com aren't supported. Use your My Domain URL instead. To find your My Domain URL, from Setup, in the Quick Find box, enter My Domain, and then select My Domain.

These parameters must be included in the request.

Here’s an example with the client credentials in a Basic authorization header. With this format, the client_id is appended to the client_secret in the format client_id:client_secret, and the resulting value is Base64-encoded.

POST /services/oauth2/token HTTP/1.1
Host: MyDomainName.my.salesforce.com
Header: Authorization: Basic 
TXlDbGllbnRJRDpNeUNsaWVudFNlY3JldA==
grant_type=client_credentials

If you use this format, the grant_type is the only required parameter in the request body. The grant_type must be set to client_credentials.

Note Because Salesforce doesn’t support scopes on the token endpoint, you can’t include scopes in the request. Instead, assign scopes to your external client app.

Salesforce Grants an Access Token

After validating the client credentials, Salesforce returns a response containing an access token and requested scopes. The app can use the access token to access protected data in Salesforce.

{
    "access_token": "*******************",
    "instance_url": "https://yourInstance.salesforce.com",
    "id": "https://login.salesforce.com/id/XXXXXXXXXXXXXXXXXX/XXXXXXXXXXXXXXXXXX",
    "token_type": "Bearer",
    "scope": "id api",
    "issued_at": "1657741493799",
    "signature": "c2lnbmF0dXJl"
}

These parameters are included in the response.