## CLI

The Depot CLI supports token-based authentication and OIDC trust relationships for container builds. For local development, use [`depot login`](/content/docs/cli/reference/overview#depot-login/index.html) to authenticate with a [user access token](/content/docs/cli/authentication#user-access-tokens/index.html). For CI, we recommend using an [OIDC trust relationship](/content/docs/cli/authentication#oidc-trust-relationships/index.html), but you can also use an [organization token](/content/docs/cli/authentication#organization-tokens/index.html) or a [project token](/content/docs/cli/authentication#project-tokens/index.html).

## Tokens

Depot supports [Organization](/content/docs/cli/authentication#organization-tokens/index.html), [Project](/content/docs/cli/authentication#project-tokens/index.html), [User](/content/docs/cli/authentication#user-access-tokens/index.html), and [Pull](/content/docs/cli/authentication#pull-tokens/index.html) tokens. Access depends on the token's scope and the operation:

| Service            | User token | Organization token | Project token    | Pull token          |
|--------------------|------------|--------------------|-------------------|---------------------|
| Container Builds    | ✅        | ✅                  | ✅ (project-scoped) | —                   |
| Registry            | ✅        | ✅                  | ✅ (project-scoped) | ✅ (read-only)      |
| Depot CI           | ✅        | ✅                  | —                 | —                   |
| Cache              | ✅        | ✅                  | —                 | —                   |
| Agents             | ✅        | ✅                  | —                 | —                   |
| API                | Some 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](/content/settings/index.html) 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](/content/orgs/_/settings/index.html) 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](/content/orgs/_/projects/index.html) 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](/content/docs/registry/quickstart#create-a-registry-access-token/index.html) with **Pull** permission for that repository.

Generate a pull token with the Depot CLI:

```shell
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`](/content/docs/cli/reference/overview#depot-login/index.html)
4. OIDC token (if available)

`depot projects get` and `depot projects update` require an [organization token](/content/docs/cli/authentication#organization-tokens/index.html). 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`:

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

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

```shell
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](https://docs.github.com/en/actions/concepts/security/openid-connect), [GitLab CI ID tokens](https://docs.gitlab.com/ci/secrets/id_token_authentication/), [CircleCI OIDC](https://circleci.com/docs/guides/permissions-authentication/openid-connect-tokens/), [Buildkite OIDC](https://buildkite.com/docs/agent/cli/reference/oidc), and [RWX](https://www.rwx.com/).

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](/content/orgs/_/projects/index.html) 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](/content/orgs/_/projects/index.html) 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`.

```yaml
    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](/content/orgs/_/projects/index.html) 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](/content/orgs/_/projects/index.html) 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](https://www.rwx.com/docs/oidc-depot) in the RWX docs.

1. Go to your [Projects page](/content/orgs/_/projects/index.html) 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**.