Creating a Personal Access Token

In integration scenarios, you need to authenticate with the Distr API using a Personal Access Token (PAT). This applies for any kind of integration, no matter whether you are using the Distr SDK or interacting with the API directly.

A Personal Access Token is a unique string that you generate in the Distr web interface. It is directly associated with the user who created it, and with the organization it was created in. It cannot be used to access data of other organizations of the same user.

Creating a Personal Access Token

In the top right corner of the Distr web interface, click on your user icon and select Personal Access Tokens from the dropdown menu. You can also directly access this page by navigating to https://app.distr.sh/settings/access-tokens (make sure to replace app.distr.sh with your Distr instance URL if you selfhost).

The page will show you a list of already granted access tokens that are associated with your user account.

On the top right corner, click on the Create token button.

You will be prompted to enter a name, an expiry date, and a role for the token. You can leave the name and expiry empty, but we recommend setting a descriptive label and an expiry date to keep your tokens organized and secure.

After you have entered the details, click on the Create button. The token will be generated and displayed on top of the page.

Scoping a token’s permissions

By default, a Personal Access Token operates with the same role you have in the organization. You can lower this when creating the token: the role dropdown only lets you pick a role equal to or below your own (admin, read_write, read_only).

The effective role on each request is the lower of the PAT’s role and your current role in the organization. That means:

• A read_only token issued by an admin user can only read. It cannot push artifacts to the registry or change deployments, even though the user could.
• If your own role is later downgraded (for example from admin to read_write), every token you issued is automatically capped at the new lower role on the next request. You do not need to revoke and reissue tokens after a demotion.

We recommend creating dedicated lower-privilege tokens for automation that does not need write access, for example a read_only token for a CI job that only pulls artifacts from the registry.

This is the only time the token will be shown to you. Make sure to copy it and store it in a secure place. Remember, anybody that has access to this token can authenticate with the Distr API on your behalf. Treat it like your password.

Deleting Personal Access Tokens

On the same page you are also able to delete tokens. Click on the trash icon next to the token you want to delete and confirm the action.

Note that any application using this token will no longer be able to authenticate with the Distr API.