API-Key
- Timothé Perez (Deactivated)
- Jens De Pelsmaeker
Introduction
API-Keys are randomly generated strings you can use to authenticate and authorize requests. They are essentially designed for Machine to Machine communication and don’t rely on session or interactive mechanisms such as login and password prompt, but can also be used to grant temporary access to resources thanks to the built in expiration (see the fully qualified link documentation).
An API-Key is a plain text token which grants privileges, therefore it must be considered as a secret and not exposed to your end-user if you don’t want to grant these privileges to your users.
An API-Key is bound to a given user, who is then responsible of all the actions performed by his tokens.
However the API-Keys have their own roles definition, making it possible to create multiple tokens with different scopes:
In this example, a single user possesses 3 tokens, each with different role scopes.
Note that to avoid privilege escalation, a user cannot have API-Keys with broader role than his own role definition - in the example the user has the 2 roles on all inboxes, so it’s allowed to create tokens on specific inboxes.
Usage
Creation and usage of API-Keys is fairly simple, although extra attention needs to be taken when setting up the correct roles and permissions. The next sections will walk you through the creation process and how to use an API-Key to make authenticated calls to our API.
The API calls example below hide the Authorization header, but all calls are made on endpoints requiring proper authentication and authorization to manage users, roles and api-keys. You can use the interactive Swagger UI to make the calls below after login with your user and password.
Use your own tenant URL: in the example below we’ll use the alfredo organization on Q.
Creation
Before creating an API-Key, you must properly set up the roles and users in your tenant:
Roles and permissions
The roles list is passed at API-Key creation and cannot be modified after: token roles are immutable.
The roles can be managed via the UI or via the API using the /roles endpoints.
curl --request GET --url https://alfredo.contract-q.fit/admin/rolesLet’s take the Operator role from the roles list and write down its id:
{
"id": "5e429c7f4657cc2eaf0e7d4f",
"name": "Operator",
"permissions": { ... }
}
Each API endpoint in the Swagger should tell you the required permission to use it:
You can alter role to add or remove permissions, depending on your intention. Keep in mind you should grant only the required permissions for your application, and not grant all permissions.
User
Each API-Key is explicitly bound to a user at creation and any action done with this token will appear as made by this user. It must be an already existing user and have at least the roles you want to give to the token.
Given my “Operator” role, I should create (one time only) a dedicated user for my operator tokens:
curl --request POST \
--url https://alfredo.contract-q.fit/admin/users \
--header 'Content-Type: application/json' \
--data '{
"username": "demo",
"active": true,
"password": "largerandomandsafepasswordnotlikethisone",
"roles": [
{"role": "5e429c7f4657cc2eaf0e7d4f"}
]
}'
This demo user has the Operator role on all inboxes: we will be able to create API-Keys with the Operator role on specific inboxes, or on all inboxes (higher or equal permissions). Write down its ID, we’ll use it later:
API-Key
The API-Key itself can only be created using the API using the /auth/api-keys endpoints, it is not yet available in the UI.
Each API-Key has the following attributes you can set:
Auto expiration date
Can be short lived or even disabled, ie non expiring
Active flag to disable the token
Roles list - NOT update-able
Each element has a Role ID (you can get this from the /roles endpoint)
an inbox scope if applicable, to restrict to an inbox
a document_id scope if applicable, to restrict to an inbox
The token value is randomly generated on our side, you cannot force it to a value of your choice.
You will get back the randomly generated token - keep it secret!
Make requests
The API-Key can be passed in 2 different ways:
HTTP Header
The recommended and simplest way is to pass the token in the X-API-KEY HTTP header with each of your requests:
Query string
You could also pass the token in the query string, although it is not recommended:
Revocation
You can temporary disable an API-Key using the PATCH endpoint:
The requests made using the API-Key will now be denied until active is reset to true.
You can permanently revoke the API-Key by deleting it - warning: this cannot be undone.
The API-Key will be removed and cannot be recovered ; since it is randomly generated you won’t get the same token again.