Personal Access Token for Authentication

This topic describes how to create and use Personal Access Tokens (PAT).

PATs are used as an alternative to passwords for authenticating with Digital.ai Release. You can use PATs with public APIs and webhook endpoints.

Note: Earlier, PATs were supported only for internal users, but now it is supported for LDAP users too. For external users, use OIDC-based authentication. For more information, see Configure OpenID Connect (OIDC) authentication for Release.

Creating a PAT

1. Log in to Digital.ai Release.
2. In the top-right corner, click your profile avatar > Access tokens. The Personal access tokens page appears.
3. On the Personal access tokens page, click Generate new tokens. The Generate token pop up screen appears in the right side of the page.
4. In the Token name field, enter a token name.
5. In the Token expiration drop-down list, select the number of days for the token to expire.
6. Select the Use all permissions radio button, if you want to use all the permissions for the token. For more information about permissions, see Global Permissions.
7. Select the Let me select permissions radio button, if you want to select some specific global permissions.
8. Click Generate to generate the token.
9. Click Copy token to copy the token, and save the token in a secure location. Once you refresh, you cannot copy the token.

Deleting a token

To delete a token, click the Delete button in the relevant row and click Delete token.

Set Expiration Period for Personal Access Token

You can now set an expiration period for the personal access token (PAT) using the Token expiration dropdown in the Personal access tokens screen from the following options.

Expiration days can be set as 7 days, 30 days, 60 days, 1 year, or No expiration. Note that, you can select No expiration from the dropdown to avoid expiration of the PAT.

Authenticating with Public APIs Using PATs

You can use the PATs for authentication with public APIs in the following ways:

• Pass PATs in API calls in place of a password
• Pass PATs in the header of an API call

Note: Users who authenticate in web application through an external ID provider, such as LDAP, Okta, or Keycloak cannot use PATs.

Pass PATs in API Calls in lieu of a Password

Here is an example for basic HTTP authentication without a username:

curl -u :<pat> 'http://localhost:5516/api/v1/releases' -i -X GET

Pass PATs in API Call's Header

Here is an example for passing the token as part of the header:

curl --header 'x-release-personal-token: <pat>' 'http://localhost:5516/api/v1/releases' -i -X GET

For run as automated user for script tasks (see Assigning an Automated Tasks User), keep the user name field blank and set the PAT as your password, and start the release.

Authenticating with Webhook Endpoints Using PATs

To use PATs with webhook endpoints:

1. From the navigation pane, under Configuration group, click Connections.

2. In the Connections page, under Webhooks and Events group, click the + icon next to HTTP Endpoint for Webhooks.
   The New HTTP Endpoint for Webhooks page is displayed.

3. Choose an HTTP endpoint by selecting one of the check boxes next to HTTP Endpoint for Webhooks.

4. Do the following:

   • In the Title field, enter a name for the configuration.
   • Select the Enabled check box.
   • In the Endpoint Path field, enter the path for the webhook endpoint.
   • In the Authentication Method drop-down list, select the Token Authentication method.
   • In the Secret Token field, enter the PAT.
   • In the Request Retention field, enter the number of requests you want to keep in the database.

5. Click Save.

   

6. To authenticate, pass the token with x-release-webhook-token header.

Admin-Controlled Token Expiry for Personal Access Tokens

Users currently have the flexibility to set any expiration date for Personal Access Tokens (PAT) or even choose the No expiration option. However, there is a security risk as tokens may remain forever unnoticed in the system. To address this concern, administrators now have the capability to oversee and limit the expiration duration set by users for PATs. This allows admins to prevent the creation of prolonged or non-expiring PATs, ensuring better security practices. To learn more about this feature, see Personal Access Token for Authentication.

Navigate to System settings > General > Personal access tokens section to set the value using the Maximum token expiration duration drop-down list.

By default, the value is set to No expiration. The available values are as follows:

• 7 days
• 30 days
• 60 days
• 1 year
• No expiration

For example, if the value is set to 30 days. The available options in the Expiration field of the Personal access tokens page will be 7 days and 30 days. You cannot set an expiration beyond 30 days.

Notify Token Expiration Timelines

A new column titled Expires in is added to provide visibility into the token expiration timelines.

The following list provides information about how the token expiration is notified:

• Never pill indicates the token does not have an expiration date.
• If the expiration date is greater than 5 days, the number of days before the expiration is displayed.
• If the expiration date is less than 5 days, a warning pill is displayed with the number of days remaining for expiration.
• If the expiration date is less than 24 hours, a warning pill is displayed with the message stating Less than 24 hours.
• If the expiry date is passed, a caution pill is displayed with the message stating Expired.