Differences

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

--- 712:api-tokens [2025/09/12 12:50] – [How to create an API-token for the Open Read API] Weinlein, Thomas
+++ 712:api-tokens [2025/09/15 15:37] (current) – [API token administration] Weinlein, Thomas
@@ Line 19: / Line 19: @@
 After that, a service restart is necessary.
-===== How to create an API token for SCIM. =====
+===== 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 Open Read API is only accessible for Process Modellers with ''CollectorData'' Read and ''Create'' permissions.
+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**.
-Please note that the API token is only shown once on creation, so make sure to copy it to a secure location for storage.
+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.