API Token

API Tokens are used for authentication when accessing XDM’s REST API. They allow users to authenticate without using their username and password, providing a more secure way to access the API.

A user can create multiple API Tokens, each with its own generated token and expiration date. Note that API Tokens are only valid for a maximum of one year, and they cannot be renewed. Once an API Token expires, a new one must be created.

If the external user is deactivated or deleted at the authentication provider, the respective XDM user has to be deactivated manually inside XDM. By this, the corresponding API Token will also be deactivated and can not be used for authentication anymore. This will not happen automatically.

For being able to use API Tokens, the user must be assigned the required role. Details on how to define the role via an environment variable can be found in the Token based authentication configuration section.

Concepts and more information

Token based authentication concepts

Properties

The table below documents the available properties for api tokens. The 'name' column displays the property name as it can be used in Groovy and Java Scripts.

Name	Type	Default	Description
Created on createdOn	Timestamp	n/a	Describes at which date the API Token was created.
Description description	String	n/a	An optional description for this object. The description can contain multiple lines to give more context on the configured object.
Name displayName	String	n/a	Specifies the name of the object. The name is used to display and identify the object in lists. The name can contain any valid UTF-8 characters. This field is mandatory.
Expire Date expireDate	Timestamp	n/a	Describes at which date the API Token expires. Once this date is reached, the API Token object is invalid. This date must be no more than one year in the future.
User user	User	n/a	Contains the user who created the API Token.

Name

Type

Default

Description

Created on

createdOn

Timestamp

n/a

Describes at which date the API Token was created.

Description

description

String

n/a

An optional description for this object. The description can contain multiple lines to give more context on the configured object.

Name

displayName

String

n/a

Specifies the name of the object. The name is used to display and identify the object in lists. The name can contain any valid UTF-8 characters. This field is mandatory.

Expire Date

expireDate

Timestamp

n/a

Describes at which date the API Token expires. Once this date is reached, the API Token object is invalid. This date must be no more than one year in the future.

User

user

User

n/a

Contains the user who created the API Token.

Actions

The available actions are described below. Some actions apply to the list, while others are specific to selected api tokens.

List Actions

The following actions are available on the api tokens list. If the action is disabled a tooltip will provide the exact reason for the deactivation. The required permissions are described in detail for each action.

Bulk Delete
Create

Delete the selected objects.

The following options are available:

Cascade: Recursively delete depending objects.

When using cascade, dependent objects are deleted first also with cascade enabled. Thus, a cascade deletion is a recursive function that deeply searches for dependent objects and deletes them first. There is only a confirmation for the first object. The dependent objects are deleted without confirmation but only when the user has the DELETE permission.

This feature is only available in development mode. More information about development mode can be found in the chapter User Settings. It should be used with caution.

An object in the result list can have two different states, these are:

DELETED: The object could be deleted.
NOT_DELETED: The object could be not deleted. This may be because the executing person does not have a delete permission on the object or the object is still referenced by others. A detailed reason can be determined with the help of the error message. If the object is still in use, these objects are also displayed.

Creates a new object in the current list. Depending on the object type either a popup dialog is shown for the most important settings, or the complete object is shown in edit mode. The dialog provides the option to create the object and remain in the current list or to switch to the newly created object in edit mode to perform further changes.

Object Actions

The following actions are available on specific api tokens. In order to execute the action, the user must possess the necessary permissions for the object. The permissions required for each action are described individually. If the user does not have these permissions, the action will be disabled and the tooltip will provide the exact reason for the deactivation.

Delete
Edit
Generate

Delete the object. If the object is still used by another entity, an error message is displayed, and the object is not deleted. The delete operation must be confirmed in a separate popup.

The following options are available:

Cascade: Recursively delete depending objects.

This feature is only available in development mode. More information about development mode can be found in the chapter User Settings. It should be used with caution.

Opens the current entity in edit mode.

This action allows to generate an API Token for token based authentication in XDM.

Refer to token based authentication concepts for more information.

API Tokens are only displayed once they are created, and they cannot be retrieved again after that. Therefore, it is important to copy the API Token immediately after its creation and securely store it.