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 Fully (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. |
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:
...
The roles list is passed at API-Key creation and cannot be modified after: a token roles are immutable.
...
Each API endpoint in the Swagger should give your 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.
You must use the same roles for the API-Key and the matching user: you can’t use different ones even if they have the same 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 permissions roles you want to give to the token.
...
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 |
...