Authentication

To keep your Dist organization secure, you must authenticate before you can access most resources on Dist. The only operation that does not required authentication is read-only access to public distribution repositories.

You can access resources in your organization in a number of ways: in a browser, with native tools, or with the API. Each way of accessing your Dist organization supports different methods of authentication as outlined below.

Authenticating with your browser

You can authenticate to your Dist organization in your browser using your email address and password. You'll create a password when you first create your organization or when you accept an invitation to the organization from an existing user. We recommend that you use a password manager to generate a strong unique password.

Authenticating with native tools

When using native tools such as build or deployment tools you must authenticate using either a personal access token or distribution key.

  • Personal access tokens — Allow existing users within an organization to generate a number of appropriately scoped and easily revokable tokens that can be used by standard tools when authenticating to your Dist organization.

  • Distribution keys — Allow read-only access to a list of protected distribution repositories. These easily revokable keys can be shared with users external to your organization.

Authenticating with the API

API documentation is coming soon.

Personal access tokens

Personal access tokens are used to authenticate API requests and repository access by native tools. They are managed from the Settings section of your organization.

Personal access tokens are unique to each user and inherit that user's roles and associated permissions. Each personal access token is also scoped, allowing each token's effective roles and permissions to be further limited.

A personal access token's scope is defined by its:

  • Permitted roles: Zero or more organization or repository roles; and
  • Coverage: All repositories, or selected repositories

The effective permissions of an access token is the minimum permissions granted by both the user's roles and the access token's scope.

For example, consider the following configuration:

  • Alice has the following repository roles:
    • Administrator access to the acme-app repository; and
    • Developer access to the acme-libs repository.
  • Alice has two personal access tokens:
    • Personal access token dev scoped to Reader for the acme-libs repository; and
    • Personal access token publish scoped to Uploader across all repositories.

Given the above configuration the following will be true:

  • Alice's dev personal access token will only have permission to Download artifacts from the acme-libs repository. It will have no permissions for the acme-apps repository.
  • Alice's publish personal access token will only have permission to Upload artifacts to both acme-app and acme-libs repository. It will have no other permissions to either repository.

Distribution keys

Distribution keys are used to authenticate read-only protected distribution repository access by native tools. They are managed from the Settings section of your organization or API by a user with either the Administrator or Distribution Key Manager organization role.

Each distribution key is scoped to a list of repositories that have protected distribution visibility. The distribution key grants read-only access to repositories in the scoped repository list. You can share distribution keys with users outside your organization to provide them with secure access to artifacts you wish to distribute. These keys can be easily revoked at any time.