Authentication - Reference | Kayako Developers

Contents

Schemes

The Kayako API supports the following authentication schemes:

Basic HTTP Authentication

The Basic HTTP authentication is an authentication standard for the HTTP protocol (while it's considered to be insecure).

To authenticate using the Basic HTTP authentication protocol you need to use the Authorization HTTP header as follows:

Authorization: Basic base64($email:$password)

Important: While we always use the HTTPS protocol for transferring data to the server, the Basic HTTP authentication should still be avoided, when possible, as it operates the user password directly.

On successful Basic HTTP authentication you should receive an API response with an additional session_id field:

{
    "status": 200,
    "session_id": "1P8xuJ4UQIWrRin2HU35V390e1d28ad230d0957c783bed37a4abe1bf6adbbB5Bw0Ja5PWO0v26lEa6z"
}

Use this session ID to authenticate in all subsequent API requests. See Session how.

Do not supply the Basic HTTP authentication header in subsequent API requests (after you have received the session ID).

In some conditions (depends on system and user configuration) a valid Basic HTTP authentication request can return an "error". If you get it, this means, that you need to go through some additional authentication step(s) to complete the authentication process (and get the session ID).

Such "error" response always comes with an additional auth_token field, the value of which you'll need to complete the authentication:

"auth_token": "qhrejryxGtnLQe40nNetYPLp5H9sCMnG82ULd7jANTcI8hW61bDoTUGdp64u"

During the very next authentication step this token should be put into the X-Token HTTP header:

X-Token: qhrejryxGtnLQe40nNetYPLp5H9sCMnG82ULd7jANTcI8hW61bDoTUGdp64u

Or into the _token argument.

Each authentication step has its own authentication token, that cannot be used for other steps (i.e. you can't use for password update the token, that was generated for OTP).

Only the Basic HTTP authentication scheme has these additional steps.

OTP authentication step

The Basic HTTP authentication can "halt", if the two-factor authentication is enabled for the user.

The two-factor authentication can be enabled for a user in the Kayako administration area.

In this case the following response is returned by the API service:

{
    "status": 403,
    "errors": [
        {
            "code": "OTP_EXPECTED",
            "message": "To complete authentication you need to provide the one-time password",
            "more_info": "https://developer.kayako.com/api/v1/reference/errors/OTP_EXPECTED"
        }
    ],
    "notifications": [
        {
            "type": "INFO",
            "message": "Two-factor authentication is enabled for your account"
        }
    ],
    "auth_token": "dPQBJfPG5cGYd6MMPtowGz93x3uSN7Vc7yBw3JrKL5owqfowKFda4mezGefo5QDmRnxyV2"
}

If this is the case, ask the user for OTP (one-time password) and pass it in the X-OTP HTTP header:

X-Token: dPQBJfPG5cGYd6MMPtowGz93x3uSN7Vc7yBw3JrKL5owqfowKFda4mezGefo5QDmRnxyV2
X-OTP: 379069

Alternatively, you can pass it in the _otp argument.

Users should use the Google Authenticator to get the OTP.

If the OTP is correct, the user will get authenticated (and the session ID will be returned) or another authentication step will be requested by the API service.

Password update step

The Basic HTTP authentication can also "halt", if the user's password has expired.

The password expiration policy can be configured using the Kayako UI.

If this happens, the following response is returned by the API service:

{
    "status": 403,
    "errors": [
        {
            "code": "CREDENTIAL_EXPIRED",
            "message": "The credential (e.g. password) is valid but has expired",
            "more_info": "https://developer.kayako.com/api/v1/reference/errors/CREDENTIAL_EXPIRED"
        }
    ],
    "auth_token": "eGDPtbMcQCXBLwef58Kz4HBCuaRPyq5QCMqFLD1iUUIGxUq48bADFUv2gRdxRJXhmduY0t37BAXeaaT1"
}

This means, that to complete the authentication you must update the user's password.

This can be done using the Change password end point. The difference with the normal password update procedure is that you provide the authentication token (instead of being authenticated) and do not need to pass the old password:

PUT /api/v1/profile/password.json HTTP/1.1
Host: brewfictus.kayako.com
X-Token: eGDPtbMcQCXBLwef58Kz4HBCuaRPyq5QCMqFLD1iUUIGxUq48bADFUv2gRdxRJXhmduY0t37BAXeaaT1

new_password=xgw4sUBXQKaQT3pg

OAuth 2.0

OAuth 2.0 is the de facto standard for API authentication nowadays.

Generally, OAuth 2.0 authentication is based on the access token. This token is like a password generated specially to be used by a particular API client.

To authenticate you should supply the OAuth 2.0 access token in the Authorization HTTP header as follows:

Authorization: Bearer 4b1442a6-38d1-ae34-9d55-adf5b41d6417

Alternatively, you can use the access_token query argument.

Usually, OAuth 2.0 client libraries add the access token header or argument automatically, so you do not need to care about these details. Most such libraries (if you use them, what is recommended) can also retrieve or refresh access tokens transparently.

An access token can be retrieved with a special OAuth 2.0 request sent to the following end points:

Authorization: /oauth/token/authorize
Token: /oauth/token

The following grant types are currently supported by Kayako:

Authorization Code: The most commonly used and recommended grant type.
User Credentials: The grant type, that involves username and password.
Refresh token: The grant type, that is to be used to refresh the access token on a regular basis.

See also the OAuth 2.0 documentation for more details.

API scopes

API scopes let restricting access of the API client to specific parts of the API service's functionality.

If the API end point is associated with the scope, which is not allowed for the API client, or if no scope is associated with it, the access to such end point for the API client will be rejected.

To make sure, that the user agrees to grant access to corresponding functionality for a third-party app, the service lists requested scopes, when asking the user to authorize the app.

Currently, Kayako supports the following scopes:

users: Access to users (including identities), organizations and teams
conversations: Access to cases (including views)
insights: Access to insights
search: Access to unified search (indirect access to users, cases and so on)
configuration: Configuration of the Kayako instance (including SLAs, automations, brands, custom fields and more)

Each of the scopes can be specified (in token retrieval request by the API client) with the optional access level (separated from the scope by colon :):

read: Read-only access to data
write: Full access to data

If the access level is not specified, :write is assumed.

Fingerprint authentication

For certain endpoints, the Kayako API allows access without requiring user credentials or a Session ID.

Such access is very limited, and should only be used when a valid session cannot be established (applications targeted primarily towards unregistered users). One such use case is Kayako Messenger, which is embeddable on other websites.

Fingerprint IDs are secret tokens (UUIDs) that are generated by the client and supplied via the X-Fingerprint-ID header. For cases where supplying a header is not possible, the query parameter _fingerprint_id can be used instead.

A client using fingerprint authentication can only view resources that were created with that very fingerprint ID.

Remember Me Token Authentication

To authenticate using Remember Me Token (stored on the client side), 2 headers are required X-RememberMe and X-Fingerprint.

X-RememberMe is received on a successful login using username and password. It is a long encrypted alphanumeric string.
X-Fingerprint is a random unique device identifier string.

The client-side is requested to send these headers with every request if the Remember Me Token is available.

Session

Session is not considered to be a complete separate authentication scheme as it is to be used by all other ones. Thus, to create a session you first need to authenticate using any of the main schemes.

Nevertheless, the session authentication can be considered to be the secondary authentication scheme for the Basic HTTP Authentication.

After the initial authentication, i.e. the first API request with authentication data, the API service returns a response with an additional session_id field delivering the ID of the just created session:

{
    "status": 200,
    "session_id": "1P8xuJ4UQIWrRin2HU35V390e1d28ad230d0957c783bed37a4abe1bf6adbbB5Bw0Ja5PWO0v26lEa6z"
}

This session ID must be supplied with all subsequent API requests in the X-Session-ID HTTP header:

X-Session-ID: 1P8xuJ4UQIWrRin2HU35V390e1d28ad230d0957c783bed37a4abe1bf6adbbB5Bw0Ja5PWO0v26lEa6z

Alternatively, the _session_id argument can be used instead.

Important: If you do not provide the session ID, each new request will create a new session. This won't only make your API requests be processed slower, but will also make it impossible for you to use some API features.