How to authenticate

🚧

Credentials Required

Working directly with the Karhoo APIs requires valid credentials (an API key or a username/password pair).
Contact Karhoo to gain full access to the platform.

Overview

There are two types of credentials that can be used with Karhoo APIs as an authorisation grant:

• API keys
• Username and Password

API keys are usually easier in utilisation and therefore should be the preferred choice for backend-to-backend integrations.

API Keys

The prerequisite for using this authorisation grant is a valid Karhoo account (registered by a Karhoo representative). Once the account is created, the user can then login to the Partner Portal and issue an API Key, which can be used directly in API calls as an authorisation grant.

Issuing API Keys

Log in to the Partner Portal using Sign in with email option.
Navigate to the API Keys and generate a new API key with a preferred access scope.

Using API Keys

API Keys enable access to Karhoo endpoints when added to the Authorization header with the ApiKey auth scheme.

POST https://rest.karhoo.com/v2/quotes 
Authorization: ApiKey <issued-api-key>
...

Username and Password [Deprecated]

❗️

Username and Password authentication is deprecated and will be removed on 01/01/2023. In case you are using this authentication method please contact Karhoo and switch to Api Keys.

The prerequisite for using this authorisation grant is a valid Karhoo account (registered by a Karhoo representative). The username and password can then be exchanged for an intermediary authorisation grant: an access token, which can be used directly in API calls.

Issuing access tokens

When you are approved as a user, you will be provided with username and password credentials. Use them first to interact with the Auth API /auth/token endpoint. A successful call to that service will respond with the following properties:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik9UWXdPRVV3T0RGQk5VWkRPRGxFUlRWRU1VRkJPRUl5UTBRd05UY3pORGMzTWtReFFUSTNNdyJ9.eyJodHRwczovL2thcmhvby5jb20vYXBwX21ldGFkYXRhIjp7InZlcnNpbx4iOxIxXjxuMXIsIxVzxXxxxxxxxxxxaG9vXxxxxxxxxxxYTdxxxxxxxxxxi00NDExLWI5NzctMjgxMzc5OGE3YzExIiwiYXV0aDB",
  "expires_in": 86400,
  "refresh_token": "Xx9x9xXxxxxxXxXxaxXx9xxxxxxxXxXx-xXxxxxxXxXx9x"
}

• access_token - a JSON Web Token (JWTs)
• expires_in - the length of time in seconds that the access_token is valid
• refresh_token - to renew the access_token before it expires

Using access tokens

Access tokens enable access to Karhoo endpoints when added to the Authorization header with the Bearer Token auth scheme.

POST https://rest.karhoo.com/v2/quotes 
Authorization: Bearer <issued-access-token>
...

See the code samples in the Karhoo API Explorer for guidance for how to correctly format working API requests.

Refreshing access tokens

These access tokens will expire after the number of seconds in the expires_in time property value. When the access_token expires, a new one is requested using the Refresh Access Token endpoint.

Access tokens enable access to Karhoo endpoints when adding it to the Authorization header as a Bearer Token . See the code samples in the Karhoo API Explorer for guidance for how to correctly format working API requests.