Personal Access Tokens

Personal Access Tokens

Personal access tokens provide a flexible and reliable method for authenticating platform API requests. They can replace session-based authentication and allow integrations to use specifically assigned permissions without exposing the account login and password.

In this article

Overview

Personal access tokens are an alternative to the default session-based API authentication method. A token can be created for a particular integration, limited to selected API operations, assigned an expiration date, and revoked whenever access is no longer required.

✓

Recommended for API integrations

Tokens are particularly useful for automation scripts and accounts protected by two-factor authentication because they avoid the additional requests required to create and verify a temporary session.

Benefits of Access Tokens

Multiple tokens Create separate tokens for different applications, scripts, services, or operational tasks.
Simpler authentication Call permitted API methods directly without first generating a short-lived user session.
Protected credentials Keep the account login and password out of scripts and external integrations.
Limited permissions Grant access only to the API operations required by a particular integration.
Controlled sharing Provide a limited token to colleagues or third-party services without granting unrestricted account access.
Expiration and revocation Set an expiration date, regenerate a token, or remove it manually at any time.

Manage Access Tokens

1

Open the account menu in the upper-right corner of the dashboard and click Settings.

User account Settings button
Open the account menu and select Settings.
2

Select the Access Tokens tab to view all personal access tokens associated with the account.

Access Tokens settings
The Access Tokens tab displays existing tokens and management tools.

The tools panel provides the following actions:

Generate Create a token by defining its description, expiration date, and permitted API methods.
Edit Change the selected token configuration or regenerate its secret value.
Copy Create a new token using the selected token’s settings as a starting point.
Remove Delete one or more selected tokens.
Refresh Reload the list and display the latest token information.

Generate an Access Token

1

Click Generate in the Access Tokens tools panel.

2

Configure the new token using the available fields:

Description Enter a clear name or purpose that identifies the application or task using the token.
Expires At Select the date through which the token remains valid. The interface uses the dd-mm-yyyy format.
API Select a predefined permission set such as Extended Access, IDE Plugins, Marketplace, or Maven Plugin, or choose Custom.
Custom permissions Manually select only the API methods required by the integration.
Search Find an API method by name while configuring custom permissions.
Only Checked Filter the permissions tree to display only the selected methods.
API Docs Open the documentation link shown when hovering over an API method.
Generate Access Token dialog
Define the token description, expiration date, API set, and allowed methods.
3

Click Generate. Enter the current account password in the confirmation window and click Continue.

Password confirmation for access token
Token changes require confirmation with the account password.
4

The platform displays the newly generated token value. Click Download or Copy, save the token securely, select I’ve saved the data, and click Done.

Save personal access token
Copy or download the token before closing the dialog.
!

The token is shown only once

The secret token value cannot be viewed again after this window is closed. Store it in a secure password manager or another protected location. Do not place it in public repositories, documentation, screenshots, or client-side code.

Edit or Copy an Access Token

Edit a Token

Select an existing token and click Edit. Update its description, expiration date, or API permissions, and confirm the changes with the account password.

Copy a Token

Select a token and click Copy to create a separate token based on the existing configuration. Review the copied settings, make any required changes, and generate the new token.

✓

Use separate tokens for separate integrations

Creating an individual token for each service makes permission management, auditing, rotation, and revocation easier.

Regenerate an Access Token

When a token value is lost, forgotten, or suspected to be exposed, select it and click Edit. In the Edit Access Token window, click the regeneration link and apply the change.

Regenerate Access Token link
Use the regeneration link to replace a lost or compromised token value.
!

Update connected integrations

Regeneration immediately invalidates the previous token value. Every application, script, or automation using the old token must be updated with the new value.

Remove an Access Token

1

Select the token that is no longer required. Use Ctrl or Shift to select multiple entries when needed.

2

Click Remove in the tools panel.

Remove Access Token button
Select one or more tokens and click Remove.
3

Confirm the removal in the pop-up window and enter the account password to complete the operation.

!

Removal is immediate

Applications using a removed token can no longer authenticate. Verify that the token is not required by an active integration before deleting it.

Use an Access Token

Use the token value in the session parameter of the required platform API method. Unlike session-based authentication, a separate request for generating a temporary session is not required.

For example, the following REST request stops an environment:

https://app.${platformDomain}/1.0/environment/control/rest/stopenv?envName=${envName}&session=${token}

Replace the placeholders as follows:

${platformDomain} The platform domain name.
${envName} The name of the target environment, such as my-project.
${token} The personal access token value. The token must include permission for the requested operation.
Stop environment API request using a token
Example of an API request authenticated with a personal access token.

A successful operation returns “result”:0. A non-zero result value indicates an error. After a successful request, return to the dashboard to verify that the target environment has stopped.

✓

Expected result

The integration can call only the API methods permitted by the token without exposing the account password or creating a temporary authentication session.

Related Documentation