Introduction
API-Key Keys are randomly generated string 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).
...
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.
| Info |
|---|
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. |
...
Each API endpoint in the Swagger should give your tell you the required permission to use it:
...
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:
| Code Block |
|---|
{
"username": "demo",
"roles": [
{
"role": "5e429c7f4657cc2eaf0e7d4f"
}
],
"active": true,
"id": "61e9790f2b0c965851c3cd6d",
"confirmed_at": null
} |
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.
...
You will get back the randomly generated token back - keep it secret!
| Code Block |
|---|
{
"token": "XXX",
"user": "61e9790f2b0c965851c3cd6d",
"active": true,
"expire_at": "2022-03-20T00:00:00+00:00",
"roles": [
{
"role": "5e429c7f4657cc2eaf0e7d4f"
}
]
} |
Make requests
The API-Key can be passed in 2 different ways:
...
You can permanently revoke the API-Key by deleting it - warning: this cannot be undone.
| Code Block |
|---|
curl --request DELETE --url https://alfredo.contract-q.fit/admin/auth/api-key/XXX |
The API-Key will be removed and cannot be recovered ; since it is randomly generated you can’t won’t get the same token again.