- Admin API (Backend) Reference
- Overview
GraphiQL IDE
Play around with our GraphQL playground in real-time:
GraphQL Interactive Playground
SDKs
We provide SDKs which make it easier for you to use the functionalities of the API in the languages that you use. Here’s what’s currently available:
You can install these SDKs like so:
Endpoint
The GraphQL API has a single endpoint which remains the same no matter what operation you perform:
Authorization
The Kana API uses API Keys to authenticate requests. You can view and manage your API Keys in the Kana dashboard. Your API Key must be present for all requests made, otherwise your requests will fail.
cURL
Node.js
Authentication to the API is performed via Bearer Authentication. Your API Key should be provided through an Authorization header (-H "Authorization: INSERT_API_KEY"). We do not require Bearer to precede the API Key.
HTTP Request Methods
Our GraphQL API only supports POST HTTP requests - you will need to use POST as this enables you to include a JSON-encoded body for the query.
Formatting Queries
When submitting a request outside of the GraphiQL IDE, the value of query in the JSON payload needs to be a string containing the GraphQL operation. Here’s an example:
Errors
We return errors under a different key and with a different type depending on if you’re querying the API directly (ie. cURL) or via one of our SDKs.
Note: Remember that responses to these GraphQL API requests will return a 200 status so don’t take the response status as sacrosanct. You can access the true status within the error.response.status field for SDK requests.
| Place | Field | Type |
|---|---|---|
| cURL / Direct | errors | Array |
| SDKs | error | Object (Typed Exception) |
Handling Errors
You can provide the onError argument with an async function when initializing the client in order to globally take actions when errors occur. The following example logs all errors upon one occurring:
If using Typescript, errors will be typed and you can check against this type. The following error types are possible:
-
SubscriptionError -
SubscriptionNotFoundError -
PackageNotFoundError -
FeatureNotFoundError -
UserNotFoundError -
AuthenticationError -
NetworkError -
Error
Retrying Upon Errors
By default, we will retry sending all calls up to 2 times when a NetworkError occurs with no backoff or delay. You can override this behaviour with the retry argument: