Authentication

To use the Kojo API every API request will require passing an Authorization header with a token.

Authorization: Bearer <OAUTH 2.0 ACCESS TOKEN OR LEGACY API KEY>

OAuth 2.0

OAuth 2.0 is the preferred method of authentication.

Create a new OAuth Client in the Kojo app. You will be given a client id and client secret. Store these somewhere safe as the secret is not recoverable once lost.

In your client code, request an access token by making a POST request to https://api.kojo.tech/oauth2/token. In your request, include grant_type=client_credentials along with your client_id and client_secret using the application/x-www-form-urlencoded format.

This token is valid for 1 hour. After it expires you will need to request a new access token.

If you believe an access token has been leaked or compromised you can delete its OAuth client. All access tokens signed by that client will no longer work.

Example

Here's an example using the curl command, though your application will need to make the request using whatever library is appropriate for your setup:

$ curl --location --request POST 'https://api.kojo.tech/oauth2/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=[CLIENT_ID]' \
    --data-urlencode 'client_secret=[CLIENT_SECRET]' \
    --data-urlencode 'grant_type=client_credentials'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
 
{
  "access_token": "eyJhbGciOiJIUzI1NiIoxN...",
  "token_type": "bearer",
  "expires_in": 3600
}

The POST /oauth2/token endpoint described above implements the OAuth 2.0 client credentials flow described in RFC 6749 Section 4.4.

API Keys (Legacy)

A legacy API key may have been provided to you by Kojo when you signed up to start using the API. Legacy API keys have no expiration. If you request a new API key the previous one will immediately become invalid upon issuance of the new API key.

Please contact Kojo immediately if you believe your key has been leaked or compromised in any way and we will promptly invalidate it and provide you with a new one.