Authentication

The Depot CLI supports token-based authentication and OIDC trust relationships for container builds. For local development, use depot login to authenticate with a user access token. For CI, we recommend using an OIDC trust relationship, but you can also use an organization token or a project token.

Tokens

Depot supports Organization, Project, and User tokens. Each token type grants full access to different Depot services depending on its scope:

User access tokens

User access tokens are tied to your Depot account and grant access to every project in every organization you belong to. When you run depot login, Depot authenticates your account and stores a user access token on your machine that all subsequent builds use by default. Use user tokens only for local development, not in CI environments.

To generate a user access token:

1. Go to your Account settings in the Depot dashboard.
2. In the API Tokens section, enter a description for your token.
3. Click Create token.
4. Copy the token and save it securely. You won't be able to retrieve the value again from the dashboard.

Organization tokens

Organization tokens are scoped to a single organization. They are not tied to a user account.

To generate an organization token:

1. Go to your Organization Settings page in the Depot dashboard.
2. In the API Tokens section, enter a description for your token.
3. Click Create token.
4. Copy the token and save it securely. You won't be able to retrieve the value again from the dashboard.

Project tokens

Project tokens are scoped to a single project in your organization. They are not tied to a user account, making them ideal for CI environments where OIDC is not available.

To generate a project token:

1. Go to your Projects page in the Depot dashboard.
2. Click on a project to open the details page.
3. Click Settings.
4. Under Project Tokens, enter a token description and click Create token.
5. Copy the token and save it securely. You won't be able to retrieve the value again from the dashboard.

Token resolution

Most Depot CLI commands accept the --token flag, which lets you pass an organization, user, or project token directly. The CLI resolves tokens in the following order:

1. --token flag
2. DEPOT_TOKEN environment variable
3. Token stored locally via depot login
4. OIDC token (if available)

OIDC trust relationships

If your CI provider supports OIDC, you can authenticate with Depot through a token exchange instead of storing static secrets. Depot integrates with GitHub Actions OIDC, CircleCI OIDC, Buildkite OIDC, and RWX.

You configure a trust relationship in Depot that maps to your CI provider's identity. When a CI job runs, it requests an access token from Depot. Depot verifies the request against your configured trust relationships and, if everything matches, returns a temporary token valid only for the duration of that job.

Trust relationship tokens have the same permissions as project tokens.

Add a trust relationship for GitHub Actions

1. Go to your Projects page in the Depot dashboard.
2. Click on a project to open the details page.
3. Click Settings.
4. Under Trust Relationships, click the Add trust relationship.
5. Select GitHub as the provider.
6. Enter a GitHub User or Organization for the trust relationship.
7. Enter the name of the GitHub repository that will build images via Depot (Note: this is the repository name, not the full URL and it must match the repository name exactly).
8. Click Add trust relationship.
9. In your workflow file, add a permissions block to your job with id-token: write and contents: read.

Add a trust relationship for CircleCI

1. Go to your Projects page in the Depot dashboard.
2. Click on a project to open the details page.
3. Click Settings.
4. Under Trust Relationships, click the Add trust relationship.
5. Select CircleCI as the provider.
6. Enter your CircleCI organization UUID (this is found in your CircleCI organization settings).
7. Enter your CircleCI project UUID (this is found in your CircleCI project settings).
8. Click Add trust relationship.

Note: CircleCI requires entering your organization and project UUID, not the friendly name of your organization or project.

Add a trust relationship for Buildkite

1. Go to your Projects page in the Depot dashboard.
2. Click on a project to open the details page.
3. Click Settings.
4. Under Trust Relationships, click the Add trust relationship.
5. Select Buildkite as the provider.
6. Enter the organization slug (i.e., buildkite.com/<org-slug>).
7. Enter the pipeline organization slug (i.e., buildkite.com/<org-slug>/<pipeline-slug>).
8. Click Add trust relationship.

Add a trust relationship for RWX

To learn about configuring a trust relationship between Depot and RWX, see OIDC with Depot in the RWX docs.

1. Go to your Projects page in the Depot dashboard.
2. Click on a project to open the details page.
3. Click Settings.
4. Under Trust Relationships, click the Add trust relationship.
5. Select RWX as the provider.
6. Enter your RWX Vault subject you configured with RWX.
7. Click Add trust relationship.