Set up OAuth 2.0

Use the OAuth 2.0 protocol to implement authentication and authorization. Authorization is essential for both testing via sandbox companies and production apps.

We’ll show you how to set up the authorization flow so users can authorize to your app and give it permission to connect to their QuickBooks Online company.

If users grant permission, our Intuit OAuth 2.0 Server sends an authorization code back to your app. Your app exchanges this code for access tokens. These tokens are tied to your users’ now authorized QuickBooks Online company (identified by the realmID).

Your app needs access tokens to make API calls and interact with payments data.

Start by signing in to your developer account and creating an app on the Intuit Developer Portal.

When you create your app, select the QuickBooks Payments scope.

This app provides the credentials you’ll need for authorization requests.

Check out the OAuth Playground to preview each step of the authorization flow. We’ve provided sample data, like the redirect URI, so you can focus on the overall flow.

Using the OAuth Playground isn’t required, but we recommend it.

While authorization is a simple step for app users, it involves several tasks on the backend. Here’s an brief overview:

Creating authorization requests

• Review the scopes you selected for your app. These determine what data and API it can access. You may want to use the openID scope to implement OpenID Connect in addition to others.
• Configure your app so it uses the correct credentials (i.e. Client ID and Client secret) and redirect URIs.
• Review the base URLs in our authorization discovery documents.
• Use this info to create authorization requests.

Managing the authorization flow

• When a user connects to your app, it sends an authorization request to the Intuit OAuth 2.0 Server.
• The user gets redirected to an authorization page where they can give your app permission to access their QuickBooks Online company and its data. This is the “user consent” step of the process.
• If the user authorizes your app, the Intuit OAuth 2.0 Server sends an authorization code back to your app.

Getting access and refresh tokens

• Your app sends the authorization code back to the Intuit OAuth 2.0 Server and exchanges it for access and refresh tokens.
• Your app extracts the latest access and refresh tokens from the server response.

Making API calls

• Use access tokens to call specific APIs and interact with users’ QuickBooks Online company data.
• When access tokens expire, use a refresh token to “refresh” the access token.
• If a refresh token expires, users need to go through the authorization flow again.

Sign in to your Intuit Developer account and get your app’s Client ID and Client secret.

If you’re implementing authorization for a live, in-production app, go to the Production section and select Keys & OAuth to get your credentials.

If you’re implementing authorization for testing with a sandbox company, go to the Development section and select Keys & OAuth to get your credentials.

OAuth 2.0 requires multiple URLs for authentication and requests for resources like tokens, user info, and credentials.

Use our discovery documents to simplify the implementation. These JSON documents, found at a well known location, contain field : value pairs and URL endpoints for authorization, token, userinfo, and other data points.

URIs handle responses from the Intuit OAuth 2.0 Server during the authorization flow. Basically, they’re your app’s endpoints.

Add at least one redirect URI for your app.

If you’re developing with a QuickBooks Online SDK, use the URI value generated by the SDK.

Create the authorization request your app will send to the Intuit OAuth 2.0 Server when users connect to your app.

Request parameters should identify your app and include the required scopes.

You can create and configure an object that defines the authorization request with the required parameters.

Here are example authorization requests for supported QuickBooks Online SDKs:

1
2
3
4
5
6
7
8
9

// Instantiate object
public static OAuth2Client oauthClient = new OAuth2Client(“clientid”, “clientsecret”, “redirectUrl”, “environment”); // environment is “sandbox” or “production”

//Prepare scopes
List<OidcScopes> scopes = new List<OidcScopes>();
scopes.Add(OidcScopes.Payment);

//Get the authorization URL
string authorizeUrl = oauthClient.GetAuthorizationURL(scopes);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

//Prepare the config
OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder("clientId", "clientSecret")
        .callDiscoveryAPI(Environment.SANDBOX).buildConfig();

//Generate the CSRF token
String csrf = oauth2Config.generateCSRFToken();

//Prepare scopes
List<Scope> scopes = new ArrayList<Scope>();
scopes.add(Scope.Payment); // add as needed

//Get the authorization URL
String url = oauth2Config.prepareUrl(scopes, redirectUri, csrf); //redirectUri - pass the callback url

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$dataService = DataService::Configure(array(
      'auth_mode' => 'oauth2',
      'ClientID' => "Client ID from the app's keys tab",
      'ClientSecret' => "Client Secret from the app's keys tab",
      'RedirectURI' => "The redirect URI provided on the Redirect URIs part under keys tab",
      'scope' => "com.intuit.quickbooks.payment",
      'baseUrl' => "Development/Production"
));
$OAuth2LoginHelper = $dataService->getOAuth2LoginHelper();
$authorizationCodeUrl = $OAuth2LoginHelper->getAuthorizationCodeURL();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Instance of client
var oauthClient = new OAuthClient({
    clientId: '<Enter your clientId>',
    clientSecret: '<Enter your clientSecret>',
    environment: 'sandbox',                                // ‘sandbox’ or ‘production’
    redirectUri: '<Enter your redirectUri>'
});

// AuthorizationUri
var authUri = oauthClient.authorizeUri({scope:[OAuthClient.scopes.Payment,OAuthClient.scopes.OpenId],state:'testState'});  // can be an array of multiple scopes ex : {scope:[OAuthClient.scopes.Payment,OAuthClient.scopes.OpenId]}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

from intuitlib.client import AuthClient
from intuitlib.enums import Scopes

//Instantiate client
auth_client = AuthClient(
    “client_id”,
    “client_secret”,
    “redirect_uri”,
    “Environment”, # “sandbox” or “production”
)

// Prepare scopes
scopes = [
    Scopes.PAYMENT,
]

// Get authorization URL
auth_url = auth_client.get_authorization_url(scopes)

1
2
3
4
5
6
7
8
9

require 'intuit-oauth'

client = IntuitOAuth::Client.new('client_id', 'client_secret', 'redirectUrl', 'environment')
scopes = [
    IntuitOAuth::Scopes::PAYMENT
]

authorizationCodeUrl = oauth_client.code.get_auth_uri(scopes)
# => https://appcenter.intuit.com/connect/oauth2?client_id=clientId&redirect_uri=redirectUrl&response_type=code&scope=com.intuit.quickbooks.payment&state=rMwcoDITc2N6FJsUGGO9

Manually create an authorization request in your app’s language. You’ll need to call the Intuit OAuth 2.0 Server endpoint, generate a URL, and define the URL’s parameters.

Get the base URI from the discovery document. You can also follow these links:

• For sandboxes and testing environments: Click here
• For production apps: Click here

Use the values from the authorization_endpoint.

Your app needs to redirect users to the authorization page via the Intuit OAuth 2.0 Server. This starts the “user consent” step of the process. We’ll call this the “authorization flow.”

The authorization flow is required when users connect to your app for the first time. It’s also required any time you change your app’s scopes (i.e. incremental authorization). Users need to grant permission again since your app needs to request access additional data.

Use the authorization URL from your authorization request, or use the following examples.

Here are example redirects for supported QuickBooks Online SDKs:

1
2

// Redirect the authorization URL
return Redirect(authorizeUrl);

1
2

//Use standard url redirect-
resp.sendRedirect(url);

1
2

//redirect users to authorization screen url
header('Location: '. $authorizationCodeUrl);

1
2

// Redirect the authUri
res.redirect(authUri);

1
2

//Using standard redirect
return redirect(auth_url)

1

redirect_to(authorizationCodeUrl);

Here’s an example authorization request URL. You’ll need to replace clientid and redirect_uri with the ones you use for your app. It specifies the QuickBooks Payments scope (i.e com.intuit.quickbooks.payments) and adds line breaks for readability:

1
2

POST https://appcenter.intuit.com/connect/oauth2?
client_id=Q3ylJatCvnkYqVKLmkH1zWlNzNWB5CkYB36b5mws7HkKUEv9aI&response_type=code&scope=com.intuit.quickbooks.payment&redirect_uri=https://www.mydemoapp.com/oauth-redirect&state=security_token%3D138r5719ru3e1%26url%3Dhttps://www.mydemoapp.com/oauth-redirect&

You can review the authorization request URI using cURL. Here’s an example:

1

curl -X POST '< Authorization URI from previous step>'

There are a few ways users can connect to your app:

• Add a “Connect to” button somewhere in your app. When users select it, your app should redirect them and start the authorization flow. Here’s a quick guide to creating button UI.
• If you list your app in the QuickBooks App Store, there are a few options. You can simply link to your app’s website where users can get your app. You can also set up Intuit Single Sign-on so users can connect to your app directly from your app page.

Since designing this UI may come later in development, we won’t focus on it here. However you decide to set up the UI, it needs to redirect users to the Intuit OAuth 2.0 Server and open the authorization page.

Preview the authorization page

This authorization page is where users authorize your app and give it permission to access their data. They’ll see your app’s name and the QuickBooks Online company they’re connecting with.

If they authorize your app, the server will redirect them back to the redirect URI you set.

At this point, your app is waiting for a response from the Intuit OAuth 2.0 Server.

If users authorize your app, the Intuit OAuth 2.0 Server sends a response to the redirect URI you specified in Step 6. The response contains an authorization code in the code field.

Copy the code value.

1
2

https://www.mydemoapp.com/oauth-redirect?state=security_token%3D138r5719ru3e1%26url
%3Dhttps://www.mydemoapp.com/oauth-redirect&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&realmId=1231434565226279

If users don’t authorize your app, the server sends an access_denied error.

If the authorization request has a scope issue, the server sends an invalid_scope error.

Your app should send the authorization code (i.e. the value of the code parameter) back to the Intuit OAuth 2.0 server to exchange it for access and refresh tokens.

Use the example code to create an object named tokenResponse. This automatically exchanges the authorization code for access and refresh tokens:

1
2

oauth2Token = oauth_client.token.get_bearer_token('the authorization code returned from authorizationCodeUrl')
# => #<IntuitOAuth::ClientResponse:0x00007f9152b5c418 @access_token="the access token", @expires_in=3600, @refresh_token="the refresh token", @x_refresh_token_expires_in=8726400>

Get the base URI from the discovery document. You can also follow these links:

• For sandboxes and testing environments: Click here
• For production apps: Click here

Create a POST request to exchange the authorization code for access and refresh tokens.

Send requests to the token_endpoint (available in the discovery document) using the following parameters:

Here’s an example token exchange request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

POST https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer HTTP/1.1
Accept: application/json
Authorization: Basic UTM0dVBvRDIwanp2OUdxNXE1dmlMemppcTlwM1d2
    NzRUdDNReGkwZVNTTDhFRWwxb0g6VEh0WEJlR3dheEtZSlVNaFhzeGxma1l
    XaFg3ZlFlRzFtN2szTFRwbw==
Content-Type: application/x-www-form-urlencoded
Host: oauth.platform.intuit.com
Body: grant_type=authorization_code&
code=L3114709614564VSU8JSEiPkXx1xhV8D9mv4xbv6sZJycibMUI&
redirect_uri=https://www.mydemoapp.com/oauth-redirect

You can review the POST request using cURL. The Authorization header should follow this format:

1

"Basic " + base64encode(client_id + ":" + client_secret)

Here’s an example cURL POST:

1
2
3
4
5
6
7

curl -X POST 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: REPLACE_WITH_AUTHORIZATION_HEADER (details below)' \
-d 'grant_type=authorization_code' \
-d 'code=REPLACE_WITH_AUTHORIZATION_CODE' \
-d 'redirect_uri=REPLACE_WITH_REDIRECT_URI'

The server returns a JSON object. The access code is the access_token field value.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
"token_type": "bearer",
"expires_in": 3600,
"refresh_token":"Q311488394272qbajGfLBwGmVsbF6VoNpUKaIO5oL49aXLVJUB",
"x_refresh_token_expires_in":15551893,
"access_token":"eJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGGlyIn0..KM1_Fezsm6BUSaqqfTedaA.
dBUCZWiVmjH8CdpXeh_pmaM3kJlJkLEqJlfmavwGQDThcf94fbj9nBZkjEPLvBcQznJnEmltCIvsTGX0ue_w45h7_
yn1zBoOb-1QIYVE0E5TI9z4tMUgQNeUkD1w-X8ECVraeOEecKaqSW32Oae0yfKhDFbwQZnptbPzIDaqiduiM_q
EFcbAzT-7-znVd09lE3BTpdMF9MYqWdI5wPqbP8okMI0l8aa-UVFDH9wtli80zhHb7GgI1eudqRQc0sS9zWWb
I-eRcIhjcIndNUowSFCrVcYG6_kIj3uRUmIV-KjJUeXdSV9kcTAWL9UGYoMnTPQemStBd2thevPUuvKrPdz3ED
ft-RVRLQYUJSJ1oA2Q213Uv4kFQJgNinYuG9co_qAE6A2YzVn6A8jCap6qGR6vWHFoLjM2TutVd6eOeYoL2bb7jl
QALEpYGj4E1h3y2xZITWvnmI0CEL_dYQX6B3QTO36TDaVl9WnTaCCgAcP6bt70rFlPYbCjOxLoI6qFm5pUwGLLp
67JZ36grc58k7NIyKJ8dLJUL_Q9r1WoUvw.ZS298t_u7dSlkfajxLfO9Q"
}

Your app is now set up with OAuth 2.0.

At this point, you can also implement Intuit Single Sign-on and OpenID Connect to further enhance authorization features.

Access tokens let your app send requests to our APIs.

Pass the access_token value in the Authorization header of requests each time your app calls an API. The value should always be: Authorization: bearer {AccessToken}

Access tokens are valid for 60 minutes (3,600 seconds). When they expire, use refresh tokens to refresh them. Learn more about access and refresh tokens.

This GET request calls the charges entity to read a given charges object. Note the access_token parameter - you’ll need to specify your own access token for your requests:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

GET https://api.intuit.com/quickbooks/v4/payments/charges/<id> ​​​
Authorization=Bearer eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..eF2J3XEDnGBjpO469rw9Dw.Gi3Oc
   UsfFm8Pnxw1aneLN-5o0j_nE0G9t6jbvAFgMy4-QYkmzUCVmgJWCj9HTZ2ojgQaKjYoEwZMO3uBvs
   QUo8UIdZIOQz_3HxXggq9VIlhihH7d1NXLiFMC8dQGtFhECGypv6xJ8Ob7Ay00CbEq_tns1wgfXXFgr
   L-FcoWtuubxHUjKE7EwlM8nB0VQG1VTwjWzEcPPTr7EjK0KQWa9vXzs6W24s09mXZMli0axYobcuB
   GuFwt4RCfxARGOdyu8J9tg-QziFPX3TwIVMsAxKLdDZkMcy1fEyXW_A0H3z6IcKzvjxFRl10cASRmNb
   wSGHk8C1W89HLbeeL_wx_Bg6qTpMBjBqnpGYMVG9vSy-fmKDPd6Uysw3DvvOYkX5pFGkln6X5F2fcdxw
   VaV05IGUyxsX-Je4UY671P54ScRVlEXTAQpnmhCiR4euadvPmKqNtk70n02ExAkMJ5UbyS2mcupPjXk7C67
   qVu2kfVMLFFdg1AKhBzlpl-KqvTsgO2-bHYpKS9qwLP1CdKw_1NxB9cvjBmGQ3S33P6WjEg_eNM.rZ1h6
   s-rQb2D_PX8dIYb5g
Accept=*/*
Content-Type=application/json;charset=UTF-8

Use refresh tokens to “refresh” expired access tokens. You can refresh access tokens without prompting users for permission.

Here are examples of refreshing access tokens. Since you’re using a supported QuickBooks Online SDK, server requests and responses get parsed internally.

1
2
3
4
5

// Instantiate object
public static OAuth2Client oauthClient = new OAuth2Client(“clientid”, “clientsecret”, “redirectUrl”, “environment”); // environment is “sandbox” or “production”

//Refresh token endpoint
var tokenResp = await oauthClient.RefreshTokenAsync(“refreshToken”);

1
2
3
4
5
6
7
8

//Prepare the config
OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder("OAuth2AppClientId", "OAuth2AppClientSecret").callDiscoveryAPI(Environment.SANDBOX).buildConfig();

//Prepare OAuth2PlatformClient
OAuth2PlatformClient client  = new OAuth2PlatformClient(oauth2Config);

//Call refresh endpoint
BearerTokenResponse bearerTokenResponse = client.refreshToken("refreshToken"); //set refresh token

1
2
3
4
5

$oauth2LoginHelper = new OAuth2LoginHelper($ClientID,$ClientSecret);
$accessTokenObj = $oauth2LoginHelper->
                    refreshAccessTokenWithRefreshToken($theRefreshTokenValue);
$accessTokenValue = $accessTokenObj->getAccessToken();
$refreshTokenValue = $accessTokenObj->getRefreshToken();

1
2
3
4
5
6
7
8

   oauthClient.refresh()
        .then(function(authResponse) {
            console.log('Tokens refreshed : ' + JSON.stringify(authResponse.json()));
        })
        .catch(function(e) {
            console.error("The error message is :"+e.originalMessage);
            console.error(e.intuit_tid);
        });

1
2
3
4
5
6
7
8
9

//Instantiate client
auth_client = AuthClient(
    “client_id”,
    “client_secret”,
    “redirect_uri”,
    “Environment”, # “sandbox” or “production”
)
// Refresh token endpoint
auth_client.refresh(refresh_token=”refresh_token”)

1

Create a POST request and use the latest refresh_token value from the most recent API server response.

Send requests to the token_endpoint (available in the discovery document) using the following parameters:

Here’s an example request:

1
2
3
4
5
6
7
8

POST /oauth2/v1/tokens/bearer HTTP/1.1
Accept: application/json
Authorization: Basic UTM0dVBvRDIwanp2OUdxNXE1dmlMemppcTlwM1d2
    NzRUdDNReGkwZVNTTDhFRWwxb0g6VEh0WEJlR3dheEtZSlVNaFhzeGxma1l
    XaFg3ZlFlRzFtN2szTFRwbw==
Content-Type: application/x-www-form-urlencoded
Body: grant_type=refresh_token&
refresh_token=Q311488394272qbajGfLBwGmVsbF6VoNpUKaIO5oL49aXLVJUB

You can review the POST request using cURL. The Authorization header should follow this format:

1

"Basic " + base64encode(client_id + ":" + client_secret)

Here’s an example cURL POST:

1
2
3
4
5
6

curl -X POST 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: REPLACE_WITH_AUTHORIZATION_HEADER (details below)'  \
-d 'grant_type=refresh_token' \
-d 'refresh_token=REPLACE_WITH_REFRESH_TOKEN'

The server returns a JSON object with a refreshed access token in the access_token field.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
"token_type": "bearer",
"expires_in": 3600,
"refresh_token":"Q311488394272qbajGfLBwGmVsbF6VoNpUKaIO5oL49aXLVJUB",
"x_refresh_token_expires_in":15551893,
"access_token":"eJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGGlyIn0..KM1_Fezsm6BUSaqqfTedaA.
dBUCZWiVmjH8CdpXeh_pmaM3kJlJkLEqJlfmavwGQDThcf94fbj9nBZkjEPLvBcQznJnEmltCIvsTGX0ue_w45h7_
yn1zBoOb-1QIYVE0E5TI9z4tMUgQNeUkD1w-X8ECVraeOEecKaqSW32Oae0yfKhDFbwQZnptbPzIDaqiduiM_q
EFcbAzT-7-znVd09lE3BTpdMF9MYqWdI5wPqbP8okMI0l8aa-UVFDH9wtli80zhHb7GgI1eudqRQc0sS9zWWb
I-eRcIhjcIndNUowSFCrVcYG6_kIj3uRUmIV-KjJUeXdSV9kcTAWL9UGYoMnTPQemStBd2thevPUuvKrPdz3ED
ft-RVRLQYUJSJ1oA2Q213Uv4kFQJgNinYuG9co_qAE6A2YzVn6A8jCap6qGR6vWHFoLjM2TutVd6eOeYoL2bb7jl
QALEpYGj4E1h3y2xZITWvnmI0CEL_dYQX6B3QTO36TDaVl9WnTaCCgAcP6bt70rFlPYbCjOxLoI6qFm5pUwGLLp
67JZ36grc58k7NIyKJ8dLJUL_Q9r1WoUvw.ZS298t_u7dSlkfajxLfO9Q"
}

If users disconnect from your app, it needs to automatically revoke access and refresh tokens. For example, this process can start when users select a Disconnect link or button somewhere in your app.

Here are request examples for supported QuickBooks Online SDKs.

Send the request to the revoke endpoint. This both revokes the access token and removes permissions.

1
2
3
4
5

// Instantiate object
public static OAuth2Client oauthClient = new OAuth2Client(“clientid”, “clientsecret”, “redirectUrl”, “environment”); // environment is “sandbox” or “production”

//Revoke token endpoint
var tokenResp = await oauthClient.RevokeTokenAsync(“refreshToken");

1
2
3
4
5
6
7
8

//Prepare the config
OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder("OAuth2AppClientId", "OAuth2AppClientSecret").callDiscoveryAPI(Environment.SANDBOX).buildConfig();

//Prepare OAuth2PlatformClient
OAuth2PlatformClient client  = new OAuth2PlatformClient(oauth2Config);

//Call revoke endpoint
PlatformResponse response  = client.revokeToken("refreshToken"); //set refresh token

1
2

$oauth2LoginHelper = new OAuth2LoginHelper($clientID,$clientSecret);
$revokeResult = $oauth2LoginHelper->revokeToken($yourToken);

1
2
3
4
5
6
7
8

oauthClient.revoke(params)
        .then(function(authResponse) {
            console.log('Tokens revoked : ' + JSON.stringify(authResponse.json()));
        })
        .catch(function(e) {
            console.error("The error message is :"+e.originalMessage);
            console.error(e.intuit_tid);
        });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

//Instantiate client
auth_client = AuthClient(
    “client_id”,
    “client_secret”,
    “redirect_uri”,
    “Environment”, # “sandbox” or “production”
)

// Refresh token endpoint
auth_client.revoke(token=”refresh_token”)

1

trueOrFalse = oauth_client.token.revoke_tokens('the_token_you_want_to_revoke')

1
2

$ ls -lsa .
$ make file

Create a POST request and include the refresh_token value for the token parameter.

Send the request to the revocation_endpoint (available in the discovery document). Here’s an example request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

POST https://developer.api.intuit.com/v2/oauth2/tokens/revoke HTTP/1.1
Accept: application/json
Authorization: Basic UTM0dVBvRDIwanp2OUdxNXE1dmlMemppcTlwM1d2
    NzRUdDNReGkwZVNTTDhFRWwxb0g6VEh0WEJlR3dheEtZSlVNaFhzeGxma1l
    XaFg3ZlFlRzFtN2szTFRwbw==
Content-Type: application/json

{
    "token": "{bearerToken or refreshToken}"
}

You can review the POST request using cURL. The Authorization header should follow this format:

1

"Basic " + base64encode(client_id + ":" + client_secret)

Here’s an example cURL POST:

1
2
3
4
5

curl -X POST 'https://developer.api.intuit.com/v2/oauth2/tokens/revoke' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: REPLACE_WITH_AUTHORIZATION_HEADER (details below)' \
-d 'token:REPLACE_WITH_REFRESH_TOKEN/REPLACE_WITH_ACCESS_TOKEN'

Refresh tokens have a rolling expiry of 100 days.

As long as refresh tokens are valid, you can use them to obtain new access tokens. Always store the latest refresh_token value from the most recent API server response. Use it to make requests and obtain new access tokens.

If 100 days pass, or your refresh token expires, users need to go through the authorization flow again and reauthorize your app.