The following guide helps guide you through the endpoints required for plugin authorization. For more details on setting up app authorization flows as a whole, check out our app authentication guide here.

​
Plugin OAuth server setup

For OAuth, you’ll need to support 4 endpoints:
  • Getting an authorization code grant
  • Requesting an access token using an authorization code
  • Requesting an access token using a refresh token
  • Revoking an access token
The endpoints must accept the requests outlined below and return responses minimally matching the outlined response shapes (additional attributes can be returned but we require at least what appears in these docs). The redirect URI we’ll use for all of our requests will be https://app.kit.com/apps/install. We’ll use Bearer Authorization to include the user’s access token on all the requests we make to your endpoints.
A diagram for this flow for apps that only require Plugin OAuth authentication can be found below. For guidance on apps that also require API authentication, also check out the app authentication guide here..
OAuth app flow

​
Get an authorization code grant

We will start the OAuth process by making a GET request to your provided aurthorization URL: 
GET <YOUR_CONFIGURED_AUTHORIZATION_URL>?
  client_id=<YOUR CONFIGURED CLIENT ID>&
  response_type=code&
  redirect_uri=https://app.kit.com/apps/install
​
client_id
string
required
Your plugin’s configured Client ID
​
response_type
string
required
code
​
redirect_uri
string
required
https://app.kit.com/apps
​
state
string
Custom state to pass to the redirect_uri and/or to protect from XSRF
    curl -G GET <YOUR CONFIGURED AUTHORIZE URL> \
        -H 'Accept: text/html'
        -d "client_id=<YOUR CONFIGURED CLIENT ID>"
        -d "response_type=code"
        -d "redirect_uri=https://app.kit.com/apps/install"
302: Redirects to https://app.kit.com/apps with authorization code parameter

​
Get a new token using an authorization code

We will then exchange the returned authorization code for a new access token by making a POST to your configured token URL, with a body like so: 
{
  "client_id": "<YOUR CONFIGURED CLIENT ID>",
  "client_secret": "<YOUR CONFIGURED CLIENT SECRET>",
  "grant_type": "authorization_code",
  "code": "abc123",
  "redirect_uri": "https://app.kit.com/apps"
}
Response schema: application/json
​
client_id
string
required
Your plugin’s configured Client ID
​
client_secret
string
required
Your plugin’s configured Client Secret
​
grant_type
string
required
authorization_code
​
code
string
The code received via the redirect uri query params
​
redirect_uri
string
required
https://app.kit.com/apps
    curl -X POST <YOUR CONFIGURED TOKEN URL> \
        -H 'Content-Type: application/x-www-form-urlencoded' \
        -H 'Accept: application/json' \
        -d '{
            "client_id": "<YOUR CONFIGURED CLIENT ID>",
            "client_secret": "<YOUR CONFIGURED CLIENT SECRET>",
            "grant_type": "authorization_code",
            "code": "abc123",
            "redirect_uri": "https://app.kit.com/apps"
}

200: Returns a token

    {
    "access_token": "YOUR_ACCESS_TOKEN_HERE",
    "expires_in": 172800,
    "refresh_token": "YOUR_REFRESH_TOKEN_HERE",
    "created_at": 1710270147
    }

Response schema: application/json

​
access_token
string
required
Access token for a user in the plugin app’s system
​
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
​
created_at
integer
required
When the access token was created

​
Get a new token using a refesh token

When the previous access token expires, we will request a new access token by making a POST to your configured refresh token URL, with a body like so: 
{
  "client_id": "<YOUR CONFIGURED CLIENT ID>",
  "grant_type": "refresh_token",
  "refresh_token": "string"
}
Response body schema: application/json
​
client_id
string
required
Your plugin’s configured Client ID
​
grant_type
string
required
refresh_token
​
refresh_token
string
required
Refresh token
    curl -X POST <YOUR CONFIGURED REFRESH TOKEN URL> \
        -H 'Content-Type: application/x-www-form-urlencoded' \
        -H 'Accept: application/json' \
        -d '{
            "client_id": "<YOUR CONFIGURED CLIENT ID>",
            "grant_type": "refresh_token",
            "refresh_token": "abc123"
        }'

200: Returns a token

    {
        "access_token": "YOUR_NEW_ACCESS_TOKEN_HERE",
        "expires_in": 7200,
        "refresh_token": "YOUR_NEW_REFRESH_TOKEN_HERE",
        "created_at": 1710271006
    }

Response schema: application/json

​
access_token
string
required
Access token for a user in the plugin app’s system
​
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
​
created_at
integer
required
When the access token was created

​
Revoke an access token

When your app is uninstalled by a creator, we will make a POST request to your revoke token URL, with a body like so: 
{
  "client_id": "<YOUR CONFIGURED CLIENT ID>",
  "client_secret": "<YOUR CONFIGURED CLIENT SECRET>",
  "token": "abc123"
}
Response body schema: application/json
​
client_id
string
required
Your plugin’s configured Client ID
​
client_secret
string
required
Your plugin’s configured Client Secret
​
token
string
required
The access token
    curl -X POST <YOUR CONFIGURED REVOKE TOKEN URL> \
        -H 'Content-Type: application/x-www-form-urlencoded' \
        -H 'Accept: application/json' \
        -d '{
            "client_id": "<YOUR CONFIGURED CLIENT ID>",
            "client_secret": "<YOUR CONFIGURED CLIENT SECRET>",
            "token": "abc123"
        }'
200: OK

​
App configuration for OAuth

To set OAuth up for your app, go to the “Authentication” tab on your app, toggle on the “Plugin” section and select “OAuth” from the “Authorization method” dropdown: plugin authentication strategies This will expand the section and offer the fields to add your:
  • Authorization URL
  • Token URL
  • Refresh token URL
  • Revoke URL
as well as the “Client ID” and “Client secret” fields for us to authenticate with your service: OAuth authorization strategy UI Once all of the fields are filled out, click save and OAuth will be set up for all plugins you create for the app.

​
Post-installation redirect

Your app may also include the option to alternatively send creators to your app, or an externally hosted onboarding flow, post signup. This can be configured using the Redirect URL after install field in your app details setting page. An example of this flow can be seen below.
example redirect flow
example redirect flow

​
Plugin scopes

When configuring OAuth for your plugins, you’re able to define scopes that specify which permissions your app requires from the creator’s account. These scopes are managed in the plugin settings page and play a crucial role in app versioning and authentication.
Configuring Scopes
In the plugin settings page, you can define the scopes your plugin requires. Kit tracks these scopes cumulatively across all plugins in your app, which means:
  • Each plugin can declare its own required scopes
  • The total scopes for your app are the combined unique scopes from all active plugins
  • Changes to cumulative scopes trigger app versioning
Scope Format Requirements
When defining scopes, follow these critical formatting rules:
  • Never include spaces in scope names - Use underscores, hyphens, camel/snake case or colons instead
    • ❌ Incorrect: "read data", "write data"
    • ✅ Correct: "read:data", "write:data", "read_data"
  • Spaces cause serialization errors when scopes are processed as arrays or comma-separated strings
  • Use consistent naming conventions across all your plugins (recommended format: action:resource)
When Scopes Trigger Re-authentication
Creators will be prompted to re-authenticate when:
  • You add a new scope to any plugin that wasn’t previously used by other plugins
  • You create a new plugin with scopes not used by existing plugins
  • The authorization strategy changes (for example, from “No authorization” to “OAuth”)
Removing scopes does not require re-authentication, making it safe to reduce permissions without disrupting users.
Testing Scope Changes
When developing and testing scope changes:
  • Plugins in test mode (created and have never been activated) require you to re-authenticate the app in your developer account when new scopes are added
  • This allows you to verify the authentication flow before affecting production users
  • Always test the complete OAuth flow with new scopes before publishing
Example
If your app has two plugins with the following scopes:
  • Product Gallery Plugin: read:products, read:inventory
  • Customer Reviews Plugin: read:products, read:reviews
Your app’s cumulative scopes are: read:products, read:inventory, read:reviews Adding write:products to either plugin would trigger a new app version and require re-authentication, while adding read:products to a new third plugin would not. For comprehensive information about app versioning and its implications for both creators and developers, see the App Versioning Guide.