API-Tokens

For an external application to connect with Stages, it needs a way to authenticate itself. This can be done with API-tokens.

Stages generates its API tokens on the basis of a unique secret that can only be set by the Stages administrator. This should be a random string value with at least 32 characters. This value should be stored in the file conf/secret.properties like this:

apitoken.secret = <value>

In the conf/config.xml file the following configuration property needs to be declared:

<property name="restapi.apitoken.secret" value="${apitoken.secret}"/>

After that, a service restart is necessary.

Users need to have READ and CREATE permissions on the API tokens permission domain to be allowed to create API tokens . In order to revoke API tokens, READ and DELETE permissions are required. Authorized Stages users can find and manage the API tokens under Administration > API Tokens.

Each token is identified by a label that is defined upon generation. The resulting token values will not be stored at the server but the server is able to identify a valid token by its value. Tokens become invalid after explicitly being revoked by the Stages administrator or after their expiry date has been reached.

Directly after creating the API Token, the token value can be copied from the Stages popup dialog and saved in a secure location. Once the dialog has been closed, it can not be retrieved anymore.

Requests to the Stages SCIM endpoint must contain the value of a valid API token in the Authorization header in the following format: Bearer <token_value> Typically, the identity providers do this under the hood. All actions will be logged at the server in the scim.log and audit-json.log files with the respective API token label as a logging context identifier.

The REST API is only accessible for Process Modellers with CollectorData Read and Create permissions.

Such a user is also allowed to create an API-token for this API. This can be done in the user settings page (click on the username in the left navigation) in the section Security and Privacy.

Directly after creating the API token, the token value can be copied from the Stages popup dialog and saved in a secure location. Once the dialog has been closed, it can not be retrieved anymore.

This API token has the same permissions as the owning user.

Requests to the Stages REST endpoint must contain the value of a valid API token in the Authorization header in the following format: Bearer <token_value> Typically, the identity providers do this under the hood. All actions will be logged at the server in the audit-json.log files with the respective API token label as a logging context identifier.

All API tokens no matter if of type SCIM or CollectorData, can be managed by an administrator with APIToken Read and Delete permissions.

So the administrator has always an overview which API tokens exist for the Stages server and is also able to disable or revoke them.