First steps

Koibox allows the use of a REST API that it makes available to its customers so that they can integrate automated workflows. This also allows integration with tools such as Make or Zapier.

Note

The API requires your center to have an active Platinum plan subscription. Otherwise, a 403 response will always be returned, even if you have active API keys.

Understanding the API keys panel

To use the API, you must first create a key. An administrator can create it from the Settings > API Keys section. This section contains a list of the center’s API keys, along with their status. You can also create, activate, deactivate, and delete keys.

Danger

Keys are passwords used by applications and must be kept secret in all moments, as they allow changes to be made at your center, even when you are not working. Do not share with anyone!

It is important to note that API keys are per center; one key cannot access the resources of another center.

1. Access the form to create an API key

   In the blue top bar, click the “New API Key” button

   

2. Name the key

   In the form that appears to create a key, you will be asked to give it a name. This is so that you can identify the key later if you need to manage it. When you have a good name, click “Create new key”.

   

3. Save and copy the key

   You will see that the form now shows a new read-only field. It is your new API key. You must save it securely, as it allows your application to perform actions in your center.

   Caution

   API keys are only shown when they are created and we never show them again, it is your responsibility to keep them safe. Support cannot help you recover a lost API key; you must deactivate it, delete it, and create a new one. Support will also never ask you for this key.

   Remember that this key is linked to the user and the center that creates it, so audit logs will show that it was that user who performed certain actions.

Make your first request

Once you have created an API key, you can start making requests. You can check that your key works correctly by calling the endpoint /api/api-key/me.

The API key must be added in the X-Koibox-Key header; if you do not add it to the request, you will receive a 401.

You should receive a 200 response with a structure similar to this:

{
  "name": "your-key-name",
  "centro": 1
}

The information you receive about the key is:

• Its name
• The identifier of the center it belongs to

Tip

Save the center identifier; it may be useful for future calls.

All set! You can go to the API reference for more information about the calls you can make to work with your center’s information.