Overview
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.
Information
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 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:
-
Generate a random string to create a salt (in PHP, you would use mt_rand() to do this)
- 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)
- base64 encode the signature (in PHP, you would use base64_encode() to do this)
- 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. ReqBin is an easy to use online cURL client. Your helpdesk comes with an 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).
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. |