Kayako REST API

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
¶meterA=valueA
¶meterB=valueB
¶meterC=valueC
&apikey=d75a00ef-08b6-5b04-5d29-d3b7ca46138a
&salt=itobgt701t5nat7oor9z4t813edc5t8d
&signature=MzNiNjk4ZmUyY2FlNjQ5YmRkNjA0YjkyYTQ0NmY5OTQ4MGVkYTIwMzZjMzFkYmJjMzk4MzgzNjNiMzZjYTE4NQ==

NOTE: The URL you use for the API depends on the URL you find at Admin Control Panel > API > Settings. From there you will use a URL similar to https://mycompany.kayako.com/api/ as your API base, but if you encounter an error after multiple attempts you might need to configure your request with https://mycompany.kayako.com/api/index.php, and by adding that it should work out fine.

Authentication

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

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

• Standard: http://example.domain.com/api/index.php?/App/Controller/Action¶meter=1&...
• With an ?e= parameter: http://example.domain.com/api/index.php?e=/App/Controller/Action¶meter=1&...

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.