Creating a token
How to create an Open API token through the company's interface and safely use it in external integrations.
Machine translation
The token is needed so that an external system can access your company's Open API. To put it simply, this is a special access key that you create through the interface and then use in integration.
What is the token for?
The token is used when you want to:
- connect an external system to the company's data;
- build reports in an external service;
- to collect data in your BI-system;
- run automatic scripts via the Open API.
Without a token, an external application will not be able to work on behalf of your company.
Where is the token created?
The token is created in the company's parameters, in the tab API Integration.
If your role does not have access to this tab or it is not displayed, most often the reason is due to the role's rights or the company's license.
What is important to know in advance
Before creating a token, it is useful to understand two things:
1. The token refers to integration
Usually, one token is created for one task. For example:
- a separate token for reporting;
- a separate token for the internal service;
- a separate token for exchanging applications.
This makes it easier to maintain order and safer to disable access if necessary.
2. The token is shown only once
After creation, the system shows the value of the token only at the time of issue. Therefore, it must be immediately stored in a safe place.
How to create a token through the interface
Step 1. Open the general company settings
Open the desired company, go to the application "Administrator" and select "General parameters".
Step 2. Go to the integration tab
Open the tab API Integration.
On this screen you will see:
- company ID;
- the token creation form;
- a list of already active tokens.
What is a company ID?
The screen also displays Company ID. It is needed for part of the integration scenarios, when the external system needs to understand which company it is working with.
This ID can be copied separately.
How to fill out the token creation form
Field 1. Token name
Enter a clear name in this field. It is better to name the token so that after a month it will be clear why it was created.
Good examples:
- BI-reporting
- Integration with the internal portal
- Unloading working hours
- Synchronization of applications
A bad example:
- Test
- New token
- API 1
The clearer the name, the easier it is to manage active tokens later.
Field 2. Validity period
Select how long the token should last.
The meaning here is simple:
- If the integration is temporary, it is better to choose a limited period.;
- If this is a permanent work scenario, you can choose a longer period.;
- if in doubt, it is better to start with a limited time and, if necessary, create a new token later.
How to complete the creation
After filling in the name and expiration date, click Create a token.
If everything was successful:
- the token will be created;
- the token value will immediately appear on the screen;
- The system will copy it to the clipboard.;
- The new token will appear in the list of active tokens.
What to do immediately after creation
After creating the token, it is better to perform three actions at once:
- save the token to a safe place;
- transfer it to the responsible developer or the system for which it was created;
- write down what scenario it is used for.
You should not store such tokens in ordinary notes, messengers unnecessarily, or shared documents without limited access.
How to understand that the token is already in use
In the list of active tokens, you can see:
- name of the token;
- Validity period;
- the date of the last use, if the token has already been used.
It's convenient if you want to understand:
- Does the integration actually work?;
- which token is still in use?;
- which token can be revoked without consequences.
How to revoke a token
If the token is no longer needed or you suspect that it might have got into the wrong place, you can revoke it right in the list of active tokens.
A review is useful if:
- Integration is complete;
- the employee or contractor is no longer working with the system;
- the token was created for the test;
- there is a risk of compromising the key.
After revocation, the external system will no longer be able to use this token.
What is the best way to organize work with tokens?
This is a practically convenient approach:
- don't use one token for all integrations;
- give each scenario its own understandable name;
- periodically check the list of active tokens;
- delete unused tokens.
It's easier to maintain order and security this way.
What else is required to work with the API
Creating a token is only the first step. For full integration, you usually also need:
- understand which API methods you will use;
- know what data you want to read or send;
- configure the external system to work with the token;
- check that the requests are actually being executed in the right context of the company.
If you are just starting to get acquainted with the Open API, it is convenient to first create a separate test token and test the basic scenario on it.