Skip to main content
Version: Deploy 25.3

Personal Access Token for Authentication

Overview​

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 Deploy. You can use PATs with public APIs and webhook endpoints.

caution

Personal Access Token (PAT) Support and SSO Considerations

PATs are supported for internal, LDAP, and SSO users. However, organizations can choose to disable PAT creation for SSO users via the Settings page.

This is especially useful for organizations using Single Sign-On (SSO) systems like Office 365, Okta, or Azure AD that want to enforce centralized identity governance. If PATs remain enabled for SSO users, those tokens can continue to grant access even after:

  • The user is disabled or deleted in the SSO provider.
  • The user’s group memberships or roles are updated.

Since Digital.ai Deploy only update user roles or status when a user logs in via SSO, any existing PATs will retain the last known access level. This may result in outdated or unauthorized access.

To ensure secure access control, organizations may disable PAT generation for SSO users, so that:

  • All UI and API access always reflects the current SSO status.
  • No orphaned tokens can bypass role or access changes managed via the SSO provider.

For external users, use OIDC-based authentication instead. See Configure OpenID Connect (OIDC) Authentication for Deploy for more information.

Managing Personal Access Tokens​

Learn how to create, configure, and manage your Personal Access Tokens for secure authentication.

Creating a PAT​

Follow these steps to generate a new Personal Access Token:

  1. Log in to Digital.ai Deploy
  2. Navigate to your profile by clicking your avatar in the top-right corner
  3. Select Access tokens
  4. Click Generate new tokens
  5. In the Generate token panel:
    • Enter a descriptive Token name
    • Select a Token expiration period
  6. Click Generate
important

Copy and store the token securely. The token will not be visible after you leave the page.

Creating a Personal Access Token

Managing Token Expiration​

Understanding token expiration settings helps you maintain secure access while ensuring continuous service availability.

Expiration Options​

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

Timezone Considerations​

  • Expiration dates are displayed in your local browser timezone
  • The "Expires in" counter shows the exact remaining time, regardless of timezone
  • This ensures consistent expiration tracking across different geographical locations

Token Expiration Table

Deleting a Token​

When a token is no longer needed, you can easily remove it to maintain security:

  1. Locate the token in the Personal access tokens list
  2. Click the Delete button
  3. Confirm by clicking Delete token

Behavior When PATs Are Disabled for SSO Users​

Digital.ai Deploy handles SSO users differently when PAT generation is disabled by an administrator.

SSO Users Without Existing Tokens​

If an SSO user does not have any previously generated tokens and PAT creation is disabled, the Access Tokens page displays an informational message. No token list is shown, and token generation is not possible.

Disabled SSO No Tokens

SSO Users With Existing Tokens​

If the SSO user has existing tokens but PAT generation is disabled, the token list remains visible. However, the Generate new tokens button is disabled, and a banner is displayed to indicate the restriction.

Disabled SSO With Tokens

Using Personal Access Tokens​

Learn how to implement PAT authentication in different scenarios, from API calls to webhook configurations.

Authenticating with Public APIs Using PATs​

You can use 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

PATs are supported for users authenticated through SSO.

Pass PATs in API Calls in Lieu of a Password​

Example for basic HTTP authentication without a username:

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

Pass PATs in API Call's Header​

Example for passing the token as part of the header:

curl --header 'x-deploy-personal-token: <pat>' 'http://localhost:4516/deployit/tokens/users' -i -X GET

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.

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
  • 45 days
  • 60 days
  • 1 year
  • No expiration

Configuring a Notification SMTP Server in Digital.ai Deploy​

Digital.ai Deploy requires a Notification SMTP server to send email notifications. If no SMTP server is configured, notifications are not delivered. You can configure an SMTP server by creating a notification.PatSmtpServer configuration item.

PAT SMTP Server

Accessing Notification SMTP Configuration​

  1. In the Explorer, navigate to Configuration.
  2. Select New > notification > PatSmtpServer.

Field Descriptions​

  • ID
    The full path of the configuration item within the Deploy Library. This value is generated automatically when you create the configuration item.
    Example: Configuration/SMTPSERVERTEST

  • Name
    A unique identifier for the SMTP configuration item. This is the display name in the Deploy Library.

  • Type
    Always set to notification.PatSmtpServer. This identifies the item as an SMTP server configuration.

  • Host*
    The hostname or IP address of the SMTP server that Deploy will use to send messages.
    Example: smtp.zoho.in

  • Port*
    The TCP port for connecting to the SMTP server. Common values include:

    • 25 – Standard SMTP (unsecured)
    • 465 – SMTP over SSL (implicit TLS)
    • 587 – SMTP with STARTTLS (recommended)

  • Username
    The login name required by the SMTP server for authentication. In most cases, this is the full email address.
    Example: user@example.com

  • Password
    The password for the SMTP account. Some providers require an application-specific password instead of a regular account password.

  • From Address*
    The email address that appears in the From field of outgoing notifications.

    note

    Many SMTP providers require this address to belong to the same domain as the configured account. Otherwise, messages may be rejected or marked as spam.

  • Test Address
    An optional email address used for sending test messages with the Send Test Mail action. This helps verify that the configuration is working before enabling notifications for all users.

  • SMTP Properties
    Advanced options passed directly to the JavaMail API. Use these settings to enable encryption, authentication, or trust specific hosts.

    Example:

    • mail.smtp.starttls.enable=true – Enables STARTTLS for secure communication

    For a complete list of available properties, refer to the Java Mail Properties.

Token Expiration Notifications​

The Expires in column shows when a Personal Access Token (PAT) will expire. Deploy can also send automated email notifications to remind users before their tokens expire.

Expires in Column​

The Expires in column uses pills to display token status:

  • Never pill: Displays when the token has no expiration date.
  • Days remaining: Displays the number of days left if expiry is more than 5 days away.
  • Warning pill (≤ 5 days): Displays the number of days left if expiry is within 5 days.
  • Warning pill (< 24 hours): Displays Less than 24 hours when expiry is imminent.
  • Expired pill: Displays Expired when the token has already expired.

PAT Expiration

Email Notifications​

Deploy can notify users by email before their tokens expire:

  • Notifications are sent based on the number of days you configure.
  • Each user receives only one notification per expiring token.
  • Subject and body are customizable, and messages support HTML formatting.
  • Notification emails are processed once per day at 1:00 AM server time. As a result, you may not receive emails immediately after the triggering event.
note

Deploy requires an SMTP server to send email notifications. If no SMTP server is configured, notifications are not sent. For configuration details, see Configuring an SMTP Server in Digital.ai Deploy.

Configuring Notifications​

To enable token expiry notifications:

  1. Go to Settings > General > Personal access tokens.
  2. Select the Enable email notifications option.
  3. Enter the number of Days before expiration to trigger notifications.
  4. Select the Email server for sending notifications. If none are available, create one under the Configurations section.

Deploy will use these settings to send expiry reminders automatically.