Skip to main content

API Tokens

The API Tokens view (Main Menu / Admin / API-Tokens) shows a list of all API Tokens and provides management capabilities for them.

Txture can be integrated with other applications by using its RESTful API. We refer to such applications as External Applications. In order to secure those integrations, JWT Tokens are used.

Sharing API Tokens

You will typically want to have one API Token per application in order to allow for fine-grained Permissions. However, this is not an enforced constraint; you can also share the same token between multiple applications.

This report is divided into two panels. The left panel shows a list of all API Tokens. You can use the filter bar at the top to search for token names. Selecting an API Token on the left panel will display its details on the right panel.

Accessing the API Token Content​

The API Token is an object managed by the Txture Server. It contains metadata, such as the name and description, and allows for revocation. However, if you want to embed a token into an external application, you need the raw JWT Token content. You can access the raw token text by clicking on Show token in the details panel of a saved token:

The displayed text is what you need to copy into your external application as key. You can also check the content (and syntactic integrity) of your token in plain text by using a token decoder, e.g. the online decoder provided by JWT.io:

Creating a new API Token​

You can create a new API Token by clicking on the add button located on top of the token list. The right panel will show a form for entering the details of the new token:

You can also add User Roles to the new API Token. The process is exactly the same as for adding User Roles to a User Account. By default, every API Token receives the All external applications role (which is implicit and not displayed on the UI). The External Application which uses the API Token will have all Permissions assigned to its User Roles.

While it is not required, we recommend to set an expiry date for your token. This will ensure that the token has a time-limited validity, even when it is not revoked explicitly.

Revoking an API Token​

In certain scenarios, you might want to revoke an API Token, i.e. preventing the Txture server from accepting any further calls authorized with this token.

Revoking a selected API Token is accomplished via the Revoke button in the API Access Information section.

This cannot be undone once the revoked token is saved.

Side-Effects of Revoking

When a token is revoked, it becomes invalid. All calls by all external applications which use this token will be rejected. Revoking a token is a permanent operation that cannot be undone.

Deleting an API Token​

Deleting an API Token revokes the token, and also removes it from the API Token list on the User Interface. You can delete a token (regardless of whether it was manually revoked before or not) by selecting it in the list and then using the delete button in the top right corner of the details report.

Authenticating a REST call with an API Token​

In order to authenticate a REST call coming from an External Application at the Txture server, you require a valid JWT Token.

  1. Create a new API Token (if you haven't already)
  2. Display its JWT Token content and copy it
  3. When creating the request, set the authorization header of the HTTP call to Bearer <token-content>, replacing <token-content> with your copied token. Please note the single space character after Bearer (which is required by the protocol).

This method will work as long as the token is valid. The token will become invalid if:

  • it is revoked or
  • it is deleted or
  • it reaches its expiry date.

In addition to the authorization via the API Token, please ensure that your token has the appropriate User Roles assigned which are necessary to perform the desired tasks.