Generate an OAuth Token Using a Refresh Token

If you don't want to generate an access token using your private key, you can use a refresh token. A refresh token is a JWT token that never expires. You can use a refresh token only to generate an access token; you can't use it to make an authenticated API call.

This is useful in cases where the client making API calls doesn't have access to the private key. A third-party system can generate the refresh token and provide it to the client making API calls.

A refresh token never expires and is used to generate access tokens used to make API calls. Be sure to safeguard refresh tokens the same way you would any password.

To get an access token using a refresh token, you must first get the refresh token. Then you use the refresh token from then on to generate an access token.

  1. Open the einstein_platform.pem file and read in the key contents.

  2. Create the JWT payload. The payload is JSON that contains:

  • sub—Your Einstein Platform Services username. You can find your username in the welcome email you receive after you get an account. If you signed up using Salesforce, your username is the email address associated with the org you signed up with.

  • aud—The API endpoint URL for generating a token.

  • exp—The expiration time in Unix time. This value is the current Unix time in seconds plus the number of seconds you want the token to be valid. For testing purposes, you can get the Unix time at Time.is.

The JWT payload looks like this JSON.

  1. Sign the JWT payload with your RSA private key to generate an assertion. The private key is contained in the einstein_platform.pem file you downloaded when you signed up for an account. The code to generate the assertion varies depending on your programming language. If you're doing manual testing, you can generate an assertion using jwt.io.

  2. Call the API and pass in the assertion along with the scope=offline parameter. You pass in all the necessary data in the -d parameter. Replace <ASSERTION_STRING> with the assertion you generated. This cURL command shows the call.

The response looks similar to this JSON.

  1. Store the refresh token.

Now that you have a refresh token, you can use it to generate an access token that you can use to call the API.

  1. Call the /v2/oauth2/token endpoint and pass the refresh token along with these parameters.
  • grant_type—Specify the string refresh_token.
  • refresh_token—The refresh token you created.
  • valid_for—Number of seconds until the access token expires. Default is 60 seconds. Maximum value is 30 days (2592000 seconds).

The response looks like this JSON.

Use the access token to make any authenticated API calls as long as the token is valid (it's not expired). When the access token expires, use the refresh token to generate a new one.

You can't use refresh token to generate another refresh token. The scope=offline parameter doesn't work for this call.

To delete a token, use the call to Delete a Refresh Token.