Skip to content

Service account

A Service account represents a technical user, for instance an external API, which can interact with the platform the same way a user would.

Instead of using emails and passwords to authenticate, they use an API key, which is sent in the headers of all the requests sent by the client.

A service account is created within the scope of a tenant and cannot be shared between multiple tenants. As for users and user groups, they can be assigned roles to resources. Available roles and permissions are shared between users, user groups, and service accounts. There is no need to duplicate user roles for service accounts.

Some endpoints are restricted to users by design. For instance, /users/current can only be used by users and not by service accounts because it would not make sense.

API keys

API keys are used to authenticate clients that consume the API with a service account. Multiple API keys can be created for a single service account.

Note

API keys are only visible upon creation. Once created, you will never be able to retrieve them.

API keys are handled with the same care as if they were passwords. Consequently, they are hashed before being stored using Argon2id, since it is currently one of the most recommended hashing functions.

Usage

To create an API key, call the API endpoint: /api/tenants/{tenantId}/service-accounts/{id}/api-keys, the response body contains a key value.

API keys must be sent with all requests in the x-api-key header.

Example:

Request 

curl 
--location 'https://domain.com/tenants/<tenantId>/service-accounts/<accountId>/api-keys'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <your token>'
--data '{
    "name": "My first API key"
}'

Response body

{
  "name": "My first API key",
  "id": "9D147168-7B85-4FC4-A647-32074454C1F1",
  "key": "3ofH7YRDsUgGzpXZgeEtmzhOml3Z9ANXCdNqMDv9qIKk5YMzjmPijN2SaoicxUPACFluBO8dhl++tujMTgY6SA=="
}

Using the API key

curl 
--location 'https://domain.com/tenants/<tenantId>/devices' 
--header 'x-api-key: 3ofH7YRDsUgGzpXZgeEtmzhOml3Z9ANXCdNqMDv9qIKk5YMzjmPijN2SaoicxUPACFluBO8dhl++tujMTgY6SA=='

Security recommendations

Service accounts and API keys must only be used in the context of a machine to machine communication over a secure channel. Since they provide the same access level as users, it is paramount to ensure that API keys do not leak.

To avoid that: - Avoid at all costs using API keys for public clients, like mobile applications or single page applications. - Limit API keys expositions: do not commit them in your source code repository and avoid using them in configuration files. - Avoid sending API keys by email; prefer password managers. - Periodically rotate the API keys.

Apply the principle of least privilege to service accounts: do not give them any unnecessary permissions to limit the issue in case of an API key leakage.