> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth refresh token flow

This guide will help you understand how to set up a standard refresh token flow for an OAuth app. For more details on which flow to use or how to set up your OAuth app within Kit, please refer to the [more general "Authentication" guide](https://developers.kit.com/api-reference/authentication.md).

We also offer example OAuth implementations:

For Node.js, see the [`oauth-express` example](https://github.com/Kit/app-examples/tree/e627873f4a37dffcb3796b3a5ff25d4f108944c4/oauth-express) in our examples repository.

## OAuth refresh token flow

**1. User initiates install from Kit's App Store**

When a user installs your app from the Kit App Store, Kit redirects them to the `Authorization URL` you've configured.

```
https://example.com/kit/oauth?redirect=https://app.kit.com/apps/1?success=true
```

From here, your app should present the user a screen to sign in (or sign up).
\[!NOTE] Kit will append a redirect query parameter to your Authorization URL that you will need to save in order to complete the flow. If you're [externally initiating the installation](https://developers.kit.com/kit-app-store/authentication.md#externally-initiating-installations) from your own site, you can also pass a `return_to` parameter to redirect creators back to a specific page after install.

**2. App requests user's Kit identity**

After the user successfully authenticates with your app, redirect them to Kit's OAuth server to request their identity.
\[!NOTE] The value supplied to redirect\_uri must be one of the Redirect URIs configured in your app's settings, found on the *Distribution* tab.

> [accordion] Example redirect
>
> ```http theme={null}
>     https://api.kit.com/v4/oauth/authorize?
>         client_id=YOUR_CLIENT_ID&
>         response_type=code&
>         redirect_uri=https://oauth2.example.com/callback&
>         state=DEF456
> ```

> [accordion] Query parameters
>
> **client\_id** `string` *required*
>
> Your app's Client ID
>
> **response\_type** `string` *required*
>
> `code`
>
> **redirect\_uri** `string` *required*
>
> URI to redirect to
>
> **scope** `string`
>
> Default scope is `public`. Fine-grained access control via scopes coming soon.
>
> **state** `string`
>
> Custom state to pass to the `redirect_uri` and/or to protect from XSRF
>
> **tenant\_name** `string`
>
> Unique, human-readable identifier for a tenant of a multi-tenant app.

> [accordion] Example Kit app configuration
>
> Found on the "Authentication" tab in your app settings:
>
> ![Example Kit app configuration](https://mintcdn.com/kit-314e57c1/dSCrspkEWxNDV3Va/images/api/oauth-kit-app-configuration.png?fit=max\&auto=format\&n=dSCrspkEWxNDV3Va\&q=85\&s=16688485e58bb23aeaff5711cd8648f0)

**3. Kit prompts user for consent**

Kit will present a consent screen that asks the user to grant or refuse your app access to their account.

> [accordion] Example Kit app OAuth page
>
> ![Kit OAuth page](https://mintcdn.com/kit-314e57c1/dSCrspkEWxNDV3Va/images/kit_app_store/kit-oauth-page.png?fit=max\&auto=format\&n=dSCrspkEWxNDV3Va\&q=85\&s=d094f2ce66f7d5eda956bd405895218f)

**4. Kit redirects to App OAuth callback with authorization code**

If the user grants access, Kit redirects the user back to the `redirect_uri` you provided when requesting the user's identity in step 2.
Kit appends a `code` query param with a temporary authorization code.
\[!NOTE] Kit also appends a state query param with the same value sent in the authorization request. This check helps verify that the user, not a malicious script, is making the request and reduces the risk of CSRF attacks.

> [accordion] Example redirect
>
> ```
> https://oauth2.example.com/callback?
>     code=mrApixZzMPnYO28KoeIZxn2mvom1Tx48S9iyrQVYVE8&
>     state=DEF456
> ```

**5. App exchanges authorization code for refresh and access tokens**

Your app uses the authorization code provided to obtain a refresh and access token.

```
    POST https://api.kit.com/v4/oauth/token
```

With a body like so:

```json theme={null}
    {
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "grant_type": "authorization_code",
        "code": "abc123",
        "redirect_uri": "https://oauth2.example.com/callback"
    }
```

> [accordion] Query parameters
>
> **client\_id** `string` *required*
>
> Your app's Client ID
>
> **client\_secret** `string` *required*
>
> Your app's Client Secret
>
> **grant\_type** `string` *required*
>
> `authorization_code`
>
> **code** `string`
>
> The code received via the redirect uri query params
>
> **redirect\_uri** `string`
>
> The redirect URI the request is coming from (must be one of your app's redirect URIs)

> [accordion] Code samples
>
> ```shell shell theme={null}
>     curl -X POST https://api.kit.com/v4/oauth/token \
>         -H 'Content-Type: application/json' \
>         -H 'Accept: application/json' \
>         -d '{
>             "client_id": "YOUR_CLIENT_ID",
>             "client_secret": "YOUR_CLIENT_SECRET",
>             "grant_type": "authorization_code",
>             "code": "abc123",
>             "redirect_uri": "https://oauth2.example.com/callback"
>         }'
> ```
>
> ```javascript Javascript theme={null}
>     const headers = {
>         'Content-Type':'application/json',
>         'Accept':'application/json'
>     };
>     const inputBody = '{
>         "client_id": "YOUR_CLIENT_ID",
>         "client_secret": "YOUR_CLIENT_SECRET",
>         "grant_type": "authorization_code",
>         "code": "abc123",
>         "redirect_uri": "https://oauth2.example.com/callback"
>     }';
>
>     fetch('https://api.kit.com/v4/oauth/token',
>     {
>         method: 'POST',
>         body: inputBody,
>         headers: headers
>     })
>     .then(function(res) {
>         return res.json();
>     }).then(function(body) {
>         console.log(body);
>     });
> ```
>
> ```ruby Ruby theme={null}
>     require 'rest-client'
>     require 'json'
>
>     headers = {
>         'Content-Type' => 'application/json',
>         'Accept' => 'application/json'
>     }
>     payload = {
>         "client_id" => "YOUR_CLIENT_ID",
>         "client_secret" => "YOUR_CLIENT_SECRET",
>         "grant_type" => "authorization_code",
>         "code" => "abc123",
>         "redirect_uri" => "https://oauth2.example.com/callback"
>     }
>
>     result = RestClient.post 'https://api.kit.com/v4/oauth/token', payload,
>         params: {
>         }, headers: headers
>
>     p JSON.parse(result)
> ```
>
> ```python Python theme={null}
>     import requests
>     headers = {
>         'Content-Type': 'application/json',
>         'Accept': 'application/json'
>     }
>     json = {
>         "client_id": "YOUR_CLIENT_ID",
>         "client_secret": "YOUR_CLIENT_SECRET",
>         "grant_type": "authorization_code",
>         "code": "abc123",
>         "redirect_uri": "https://oauth2.example.com/callback"
>     }
>
>     r = requests.post('https://api.kit.com/v4/oauth/token', headers = headers, json = json)
>
>     print(r.json())
>
> ```

> [accordion] Example response
>
> **200**: Returns a token
>
> ```json theme={null}
> {
>     "access_token": "YOUR_ACCESS_TOKEN_HERE",
>     "token_type": "Bearer",
>     "expires_in": 172800,
>     "refresh_token": "YOUR_REFRESH_TOKEN_HERE",
>     "scope": "public",
>     "created_at": 1710270147
> }
> ```
>
> Response schema: *application/json*
>
> **access\_token** `string` *required*
>
> Access token that can be used to make API requests on behalf of the authenticated user
>
> **token\_type** `string` *required*
>
> `Bearer`
>
> **expires\_in** `integer` *required*
>
> When the access token expire in seconds
>
> **refresh\_token** `string` *required*
>
> Refresh token that can be used to generate a new access token once this one expires
>
> **scope** `string` *required*
>
> The scopes available for the access token
>
> **created\_at** `integer` *required*
>
> When the access token was created

**6. App redirects user back to Kit**

Now that the user has completed the OAuth flow, your app must send the the user back to Kit using the `redirect` parameter provided at the beginning of the flow.
This will ensure the user properly navigates back to your app inside of Kit and registers that the app has been installed.&#x20;
\[!NOTE] If you have set up the `Redirect URL after install` field in your app's settings, a modal prompting creators to continue their journey on your configured site will appear at this point. See this section in the [app details page guide](https://developers.kit.com/kit-app-store/app-details-page.md#how-to-configure) for more details. If the installation was [externally initiated](https://developers.kit.com/kit-app-store/authentication.md#externally-initiating-installations) with a `return_to` parameter, the creator is redirected directly to that URL instead.

> [accordion] Example redirect flow
>
> ![example redirect flow](https://mintcdn.com/kit-314e57c1/dSCrspkEWxNDV3Va/images/kit_app_store/example-redirect-flow.gif?s=a5edb0b666ed88fa29381ae689da5323)

**7. App uses access token to make Kit API calls**

Your app can now make calls to Kit's API on behalf of the user by passing a `Authorization` header with the token as a `Bearer` value.

> [accordion] Code samples
>
> ```shell shell theme={null}
>     curl -X GET https://api.kit.com/v4/account \
>         -H 'Accept: application/json' \
>         -H 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE'
> ```
>
> ```javascript Javascript theme={null}
>     const headers = {
>         'Accept':'application/json',
>         'Authorization':'Bearer YOUR_ACCESS_TOKEN_HERE'
>     };
>
>     fetch('https://api.kit.com/v4/account',
>     {
>         method: 'GET',
>         headers: headers
>     })
>     .then(function(res) {
>         return res.json();
>     }).then(function(body) {
>         console.log(body);
>     });
> ```
>
> ```ruby Ruby theme={null}
>     require 'rest-client'
>     require 'json'
>
>     headers = {
>         'Accept' => 'application/json',
>         'Authorization' => 'Bearer YOUR_ACCESS_TOKEN_HERE'
>     }
>
>     result = RestClient.get 'https://api.kit.com/v4/account',
>         params: {
>         }, headers: headers
>
>     p JSON.parse(result)
> ```
>
> ```python Python theme={null}
>     import requests
>     headers = {
>         'Accept': 'application/json',
>         'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE'
>     }
>
>     r = requests.get('https://api.kit.com/v4/account', headers = headers)
>
>     print(r.json())
> ```

**8. App uses refresh token to obtain new access token after expiration**

The access token will eventually expire and a new one must be obtained using the refresh token obtained earlier. To do this, make a `POST` call to `https://api.kit.com/v4/oauth/token`, with the following body:

> [!NOTE]
>
> Refresh tokens are single-use. The response below returns a new `refresh_token` — store it and use it on the next refresh. The refresh token you just submitted is now revoked; reusing it returns an `invalid_grant` error.

```json theme={null}
    {
        "client_id": "YOUR_CLIENT_ID",
        "grant_type": "refresh_token",
        "refresh_token": "abc123"
    }
```

> [accordion] Query parameters
>
> **client\_id** `string` *required*
>
> Your app's Client ID
>
> **grant\_type** `string` *required*
>
> `refresh_token`
>
> **refresh\_token** `string` *required*
>
> The refresh token

> [accordion] Code samples
>
> ```shell shell theme={null}
> curl -X POST https://api.kit.com/v4/oauth/token \
>     -H 'Content-Type: application/json' \
>     -H 'Accept: application/json' \
>     -d '{
>         "client_id": "YOUR_CLIENT_ID",
>         "grant_type": "refresh_token",
>         "code": "abc123"
>     }'
> ```
>
> ```javascript Javascript theme={null}
>     const headers = {
>         'Content-Type':'application/json',
>         'Accept':'application/json'
>     };
>     const inputBody = '{
>         "client_id": "YOUR_CLIENT_ID",
>         "grant_type": "refresh_token",
>         "code": "abc123"
>     }';
>
>     fetch('https://api.kit.com/v4/oauth/token',
>     {
>         method: 'POST',
>         body: inputBody,
>         headers: headers
>     })
>     .then(function(res) {
>         return res.json();
>     }).then(function(body) {
>         console.log(body);
>     });
> ```
>
> ```ruby Ruby theme={null}
>     require 'rest-client'
>     require 'json'
>
>     headers = {
>         'Content-Type' => 'application/json',
>         'Accept' => 'application/json'
>     }
>     payload = {
>         "client_id" => "YOUR_CLIENT_ID",
>         "grant_type" => "refresh_token",
>         "code" => "abc123"
>    }
>
>     result = RestClient.post 'https://api.kit.com/v4/oauth/token', payload,
>         params: {
>         }, headers: headers
>
>     p JSON.parse(result)
> ```
>
> ```python Python theme={null}
>     import requests
>     headers = {
>         'Content-Type': 'application/json',
>         'Accept': 'application/json'
>     }
>     json = {
>         "client_id": "YOUR_CLIENT_ID",
>         "grant_type": "refresh_token",
>         "code": "abc123"
>     }
>
>     r = requests.post('https://api.kit.com/v4/oauth/token', headers = headers, json = json)
>
>     print(r.json())
> ```

> [accordion] Example response
>
> **200**: Returns a token
>
> ```json theme={null}
>     {
>         "access_token": "YOUR_NEW_ACCESS_TOKEN_HERE",
>         "token_type": "Bearer",
>         "expires_in": 7200,
>         "refresh_token": "YOUR_NEW_REFRESH_TOKEN_HERE",
>         "scope": "public",
>         "created_at": 1710271006
>     }
> ```
>
> Response schema: *application/json*
>
> **access\_token** `string` *required*
>
> Access token that can be used to make API requests on behalf of the authenticated user
>
> **token\_type** `string` *required*
>
> `Bearer`
>
> **expires\_in** `integer` *required*
>
> When the access token expire in seconds
>
> **refresh\_token** `string` *required*
>
> Refresh token that can be used to generate a new access token once this one expires
>
> **scope** `string` *required*
>
> The scopes available for the access token
>
> **created\_at** `integer` *required*
>
> When the access token was created


## Related topics

- [Changelog](https://developers.kit.com/changelog.md)
- [OAuth token revocation](https://developers.kit.com/api-reference/oauth-token-revocation.md)
- [API Authentication](https://developers.kit.com/api-reference/authentication.md)
- [OAuth authorization](https://developers.kit.com/plugins/oauth-authorization.md)
- [Quick start guide](https://developers.kit.com/kit-app-store/quick-start-guide.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.