Depot
Log in
CLI

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, User, and Pull tokens. Access depends on the token's scope and the operation:

ServiceUser tokenOrganization tokenProject tokenPull token
Container Builds✅✅✅ (project-scoped)—
Registry✅✅✅ (project-scoped)✅ (read-only)
Depot CI✅✅——
Cache✅✅——
Agents✅✅——
APISome endpoints✅——

The core ProjectService's getProject, updateProject, and listProjects API calls require an organization token. createProject and deleteProject also accept user tokens, subject to your permissions. The CLI's depot projects list command uses a different endpoint and accepts user tokens.

User access tokens

User access tokens are tied to your Depot account and follow your permissions in the organizations you belong to. They cannot authenticate operations that require organization tokens, including depot projects get and depot projects update. When you run depot login, Depot authenticates your account and stores a user access token on your machine that subsequent builds use by default unless you supply another token. 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.

Pull tokens

Tokens generated by depot pull-token grant temporary, read-only access to a project's images in Depot Registry. A token covers repository paths named <project-id> or beginning with <project-id>/. It doesn't cover custom repository names outside those paths. It can't push images or authenticate to other Depot services.

To pull from a repository with a custom name, such as my-app, use a registry access token with Pull permission for that repository.

Generate a pull token with the Depot CLI:

depot pull-token --project <project-id>

Pull tokens expire after one hour and are not listed or manageable 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)

depot projects get and depot projects update require an organization token. User tokens from depot login and project-scoped OIDC tokens do not work for these commands. Create an organization token in Organization Settings > API Tokens and pass it with --token or DEPOT_TOKEN:

depot projects get <project-id> --token <organization-token>

To use the same token for subsequent commands, set DEPOT_TOKEN:

export DEPOT_TOKEN="<organization-token>"
depot projects update <project-id> --name "New project name"

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, GitLab CI ID tokens, 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.

After its first successful use, a GitHub trust relationship is tied to that repository. It keeps working if you rename or transfer the repository, and a different repository that later takes the old name can't use it.

Add a trust relationship for GitLab CI

  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 GitLab CI as the provider.

  6. Enter the GitLab namespace ID for the group or user namespace that owns the project.

  7. Enter the GitLab project ID.

  8. Optionally select Restrict to protected refs to only allow jobs from GitLab protected refs.

  9. Click Add trust relationship.

  10. In your .gitlab-ci.yml, configure a job ID token named DEPOT_OIDC_TOKEN with the audience https://depot.dev.

    build-image:
  id_tokens:
    DEPOT_OIDC_TOKEN:
      aud: https://depot.dev
  script:
    - depot build .

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.