API-Key

Introduction

API-Key are randomly generated string 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 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 are 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.

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/roles

Let’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 give your 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:

{
	"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.

curl --request GET --url https://alfredo.contract-q.fit/admin/auth/api-key

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.

curl --request POST \
  --url https://alfredo.contract-q.fit/admin/auth/api-key \
  --header 'Content-Type: application/json' \
  --data '{
	"user": "61e9790f2b0c965851c3cd6d",
	"roles": [
		{"role": "5e429c7f4657cc2eaf0e7d4f"}
	],
	"expire_at": "2022-03-20T00:00:00Z",
	"active": true
}'

You will get back the randomly generated token back - keep it secret!

{
	"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:

HTTP Header

The recommended and simplest way is to pass the token in the X-API-KEY HTTP header with each of your requests:

curl --request GET \
  --url https://alfredo.contract-q.fit/admin/inboxes \
  --header 'X-API-KEY: XXX'

Query string

You could also pass the token in the query string, although it is not recommended:

curl --request GET --url 'https://alfredo.contract-q.fit/admin/inboxes?api_key=XXX'

Revocation

You can temporary disable an API-Key using the PATCH endpoint:

curl --request PATCH \
  --url https://alfredo.contract-q.fit/admin/auth/api-key/XXX \
  --header 'Content-Type: application/json' \
  --data '{
	"active": false
}'

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.

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 get the same token again.