Setting up OAuth

You'll need to set up OAuth if you're building an integration with Katana that accesses other peoples' Katana data. You can do this in a few simple steps.

Register your application

Reach out to Katana App Partners team to get started. Firstly, you'll need to provide your app's redirect URLs. This is the URL that we POST an authorization code to when your Katana user has authorized your app to use open API on their behalf. In other words, it's the URL that Katana will use to send the authorization code for your user.

Katana team will provide you client_id and client_secret.

Get the authorization code

To get the authorization code, you need to send a GET request to https://login.katanamrp.com/authorize.

GET https://login.katanamrp.com/authorize?
    scope=offline_access&
    response_type=code&
    audience=https://api.katanamrp.com&
    client_id=<Your client ID>&
    redirect_uri=<Your redirect URI>

Your user will follow this link to the Katana site and be presented with the permissions your app is requesting. Once the user approves this request, they are redirected back via the redirect URLs you provided earlier.

Trade your authorization code for an access token

The access token is a unique key used to make requests to the API.

To get an access token, the application must make a POST request to https://login.katanamrp.com/oauth/token with the grant_type, client_id, client_secret, redirect_uri, and code as parameters.

POST https://login.katanamrp.com/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=<Your client ID>&client_secret=<Your client secret>&redirect_uri=<Your redirect URI>&code=<Your authorization code>

Use your token

Now that you have the access token, you can use this to execute queries on behalf of the user. Use the token in the Authorization header. You can find more from the general API authentication article.

Refreshing your access token

A refresh token is a unique token returned when trading the authorization code for an access token. You must use the refresh token to request a new access token when the existing one expires.

🚧

Make sure to include offline_access scope to get the refresh token. The refresh token is omitted from request responses unless this scope is included when requesting the authorization code.

To get an access token using a refresh token, the application must make a POST request to https://login.katanamrp.com/oauth/token with the grant_type, client_id, client_secret, redirect_uri, and refresh_token as parameters.

POST https://login.katanamrp.com/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=<Your client ID>&client_secret=<Your client secret>&redirect_uri=<Your redirect URI>&refresh_token=<Your refresh token>

🚧

When the access token is refreshed, a new refresh token is generated. The new refresh token should be stored and used the next time token is refreshed. Using an expired refresh token will return an error.