Page tree
Skip to end of metadata
Go to start of metadata

The "Kayako REST API" lets you quickly develop applications to connect and integrate into your Kayako helpdesk.

Whether building a custom plugin, connecting Kayako to another app or pulling data from Kayako into your other internal systems, the API lets you retrieve, add and modify data in your helpdesk. Almost every object in Kayako (whether it is a ticket, user, staff, etc) can be manipulated using the API.

REST Basics

A request to the Kayako REST API request is simply an HTTP request with the URL set to the path of the helpdesk app (such as Base), controller (like User) and parameters containing the payload of the request. The Kayako API is a "RESTful web API" (read more about the format on Wikipedia). The API uses plain XML for receiving and dispatching data.

The API uses all four REST commands - GET, PUT, POST, DELETE. These commands correspond to respective actions inside the helpdesk:?

POST and PUT are not interchangeable. Each has a specified function.

Command

Action

Description

POST

Create

Create an item (such as a ticket)

GET

Retrieve (Read)

Retrieve an item or list of items (such as a list of tickets)

PUT

Update

Modify an existing item or list of items (such as changing the owner of an existing ticket)

DELETE

Delete

Permanently remove an item or group of items (such as deleting a helpdesk user)

Your helpdesk API URL

Your helpdesk API can be accessed at your-helpdesk-URL/api/. For example:

http://example.domain.com/path-to-helpdesk/api/

What a request looks like

https://example.domain.com/api/index.php
 ?e=/App/Controller/Action
 &parameterA=valueA
 &parameterB=valueB
 &parameterC=valueC
 &apikey=d75a00ef-08b6-5b04-5d29-d3b7ca46138a
 &salt=itobgt701t5nat7oor9z4t813edc5t8d
 &signature=MzNiNjk4ZmUyY2FlNjQ5YmRkNjA0YjkyYTQ0NmY5OTQ4MGVkYTIwMzZjMzFkYmJjMzk4MzgzNjNiMzZjYTE4NQ==

Authentication

Permissions

Unlike the Kayako Staff API, the REST API does not require a staff user account to authenticate. The REST API authenticates to the helpdesk using an API key and a secret - using the API key your connecting application has access to all of your helpdesk's data. This means that the REST API has no concept of staff, team or department permissions.

Every request you make to the API must carry with it an API key, a randomly generated salt string and a signature.

Component

Where to find it

Information

API key

In the administrator control panel (under REST API).

 

Salt

Randomly generated for every request you make to the API.

 

Signature

Computed by hashing the salt and the secret key for every request you make to the API.

The signature is a SHA256 hash of the salt with the secret key used as the hashing key.

Secret key

In the administrator control panel (under REST API).

The secret key is never sent in your API requests. It is only used as the key to compute the signature.

Generating the signature

To generate a request signature:

  1. Generate a random string to create a salt (in PHP, you would use mt_rand() to do this)
  2. Generate the signature by hashing the salt using SHA256 with the secret key as the key (in PHP, you would use hash_hmac() to do this)
  3. base64 encode the signature (in PHP, you would use base64_encode() to do this)
  4. URL encode the output (in PHP, you would use urlencode() to do this)

It is recommended that the value of salt be randomized for every request to ensure secure authentication.

See code examples for generating the signature.

Testing the API

Test the API using cURL

Testing the API out? We recommend using cURL. hurl.it is an easy to use online cURL client.

Your helpdesk comes with a API Test Controller which you can use to quickly test your REST API implementation.

Advanced

Request URL type

Some customers on certain types of web server run into problems using one, but not the other (often relating to rewrite rules, or security packages).

Kayako OnDemand customers should use the standard request URL type.

If you are unsure, use the standard request URL type.

Arrays

To post an array using the query string, you should list each item in the array like this:

?usergroupid[]=2&usergroupid[]=3&usergroupid[]=X

The above example will essentially pass an array to your helpdesk containing ("2", "3", "X") for the parameter usergroupid.

Response

The server's response to a REST API request will always be an HTTP response with a status code representing the result of the request.

Some responses will contain a payload in the body and some will not.

Response code

Description

200 OK

The request was processed successfully.

400 Bad Request

The request cannot be fulfilled due to bad syntax.

401 Unauthorized

Similar to 403 Forbidden, but specifically for use when authentication is possible but has failed or not yet been provided.

403 Forbidden

The request was a legal request, but the server is refusing to respond to it.

404 Not Found

The requested resource could not be found but may be available again in the future.

405 Not Allowed

A request was made of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource.

  • No labels