Differences

This shows you the differences between two versions of the page.

--- 712:api-tokens [2025/09/11 14:14] – created Weinlein, Thomas
+++ 712:api-tokens [2025/09/15 15:37] (current) – [API token administration] Weinlein, Thomas
@@ Line 1: / Line 1: @@
-API-Tokens
+====== API-Tokens ======
-Server configuration
+For an external application to connect with Stages, it needs a way to authenticate itself. This can be done with API-tokens.
+===== Server configuration / Setting the Token secret =====
+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:
+<code ->
+apitoken.secret = <value>
+</code>
+In the conf/config.xml file the following configuration property needs to be declared:
+<code ->
+<property name="restapi.apitoken.secret" value="${apitoken.secret}"/>
+</code>
+After that, a service restart is necessary.
+===== How to create an API token for SCIM =====
+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.
+{{ :712:issue-token.jpg }}
+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.
+===== How to create an API-token for the REST API =====
+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.
+===== API token administration =====
+All API tokens no matter if of type SCIM or CollectorData, can be managed by an administrator with ''APIToken Read'' and ''Delete'' permissions.
+{{ 712:token-overview.jpg }}
+So the administrator has always an overview which API tokens exist for the Stages server and is also able to disable or revoke them.
-How to create an API token for SCIM.
-How to create an API token for Open Read API