This guide will help you understand how to set up a PKCE OAuth flow for your Kit 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.

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).

Kit will append a redirect query parameter to your Authorization URL that you will need to save in order to complete the flow.

2

App generates code verifier and challenge

efore redirecting the user to the authorization server, the app must first generate a secret code verifier and challenge.

The code verifier is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.

Once the app has generated the code verifier, it uses that to create the code challenge. The code challenge is a BASE64-URL-encoded string of the SHA256 hash of the code verifier.

The app will need to store the code_verifier for later use.

3

App requests user's Kit identity

After the user successfully authenticates with your app and the code verifier and challenge have been generated, redirect them to Kit’s OAuth server to request their identity.

The value supplied to redirect_uri must be one of the Redirect URIs configured in your app’s settings, found on the Distribution tab.

4

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.

5

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.

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.

6

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://app.kit.com/oauth/token

With a body like so:

    {
        "client_id": "YOUR_CLIENT_ID",
        "code_verifier": "add75a87509bca16dead084e7908824c8373cdeeb28341ae44713a6879f47be8f8fe6edfe9b8fa6917535e",
        "grant_type": "authorization_code",
        "code": "abc123",
        "redirect_uri": "https://oauth2.example.com/callback"
    }
7

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.

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 for more details.

8

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.

9

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://app.kit.com/oauth/token, with the following body:

    {
        "client_id": "YOUR_CLIENT_ID",
        "grant_type": "refresh_token",
        "refresh_token": "abc123"
    }

This guide will help you understand how to set up a PKCE OAuth flow for your Kit 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.

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).

Kit will append a redirect query parameter to your Authorization URL that you will need to save in order to complete the flow.

2

App generates code verifier and challenge

efore redirecting the user to the authorization server, the app must first generate a secret code verifier and challenge.

The code verifier is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.

Once the app has generated the code verifier, it uses that to create the code challenge. The code challenge is a BASE64-URL-encoded string of the SHA256 hash of the code verifier.

The app will need to store the code_verifier for later use.

3

App requests user's Kit identity

After the user successfully authenticates with your app and the code verifier and challenge have been generated, redirect them to Kit’s OAuth server to request their identity.

The value supplied to redirect_uri must be one of the Redirect URIs configured in your app’s settings, found on the Distribution tab.

4

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.

5

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.

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.

6

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://app.kit.com/oauth/token

With a body like so:

    {
        "client_id": "YOUR_CLIENT_ID",
        "code_verifier": "add75a87509bca16dead084e7908824c8373cdeeb28341ae44713a6879f47be8f8fe6edfe9b8fa6917535e",
        "grant_type": "authorization_code",
        "code": "abc123",
        "redirect_uri": "https://oauth2.example.com/callback"
    }
7

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.

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 for more details.

8

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.

9

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://app.kit.com/oauth/token, with the following body:

    {
        "client_id": "YOUR_CLIENT_ID",
        "grant_type": "refresh_token",
        "refresh_token": "abc123"
    }