Integrations: API Applications

API Applications are a secure way to interact with Linkurious Enterprise's API programmatically. They allow you to define a set of permissions and generate an API key that can be used to authenticate requests to the API.

Principles

An API Application is defined by:

• A name
• A list of user groups on whose behalf the application can act.
• A list of API actions that the application is allowed to perform.

Once created, an API Application is associated with an API key, which is a secret that can be used to authenticate requests to the API.

Restrictions

API Applications can be used to call any API endpoint, with the following exceptions:

• API Applications cannot be used to list, create or manage other API Applications (/api/admin/applications* endpoints).
• API Applications cannot be used to fetch the technical logs of the system (GET /api/admin/report endpoint).
• API Applications cannot be used to edit the currently impersonated user (PATCH /api/auth/me endpoint).
• API Applications cannot be used to restart the system (POST /api/admin/restart endpoint).

Using an API Application

⚠️ Make sure you access the API over HTTPS so your API key is not exposed.

To use an API Application, you need:

• An API key that belongs to an existing API Application
• A user email. The user must be a member of a group that the API Application is allowed to act on behalf of.

When making requests to the API, use the Basic Authentication scheme with the following credentials:

• User: The email of the user that the API Application is acting on behalf of.
• Password: The API key associated with the API Application.

If your HTTP client library does not natively support Basic Authentication, the following is equivalent to the above:

• Define CREDENTIALS as the Base64-encoded value of USER_EMAIL:API_KEY (i.e., concatenation of the user email, the : character, and the API key).
• Add an Authorization header to your HTTP requests with this value: Basic CREDENTIALS (i.e., concatenation of the string Basic and the CREDENTIALS string created above).

How to create an API Application

To create an API Application, several options are available:

1. Use the API
2. Use environment variables

ℹ️ API Applications that can act on behalf of the "admin" group can only be created using environment variables.

Using the API

You can use the API to create an API Application. The response body contains the generated API key.

Using environment variables

You can use a set of environment variables to create an API Application that can act on behalf of the "admin" group. This API Application will be granted all existing API actions (see exceptions).

This can be handy if you need to use the API before any user has been created in the system.

Follow these steps:

1. Set the LKE_ADMIN_APPLICATION_NAME and LKE_ADMIN_APPLICATION_APIKEY environment variables on the application server.
2. Use the API Application. You can use user@linkurio.us as the user's email if no user exists on the system yet.