Skip to content

Clarify Tag History API token retrieval for private images (DOCS-136) #3797

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
matthewhelmke merged 1 commit into from
Aug 18, 2026
Merged

Clarify Tag History API token retrieval for private images (DOCS-136) #3797

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions content/chainguard/containers/features/using-the-tag-history-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ aliases:
type: "article"
description: "Learn how to use the Chainguard Containers Tag History API to fetch the tag history of image variants."
date: 2023-05-26T08:49:31+00:00
lastmod: 2026-08-03T18:16:45+00:00
lastmod: 2026-08-18T17:14:56+00:00
draft: false
tags: ["Chainguard Containers"]
images: []
Expand Down Expand Up @@ -57,13 +57,21 @@ auth_header="Authorization: Bearer $(curl 'https://cgr.dev/token?scope=repositor

### Private containers

You'll need to use your Chainguard Docker credentials. This assumes you've set up authentication with [chainctl auth configure-docker](https://edu.chainguard.dev/chainguard/chainguard-registry/authenticating/):
For private images, you need a registry token scoped to the `cgr.dev` audience. After you authenticate with `chainctl auth login`, the most direct way to get one is `chainctl auth token`:

```shell
auth_header="Authorization: Bearer $(chainctl auth token --audience cgr.dev)"
```

The `--audience cgr.dev` flag is required. Without it, `chainctl auth token` issues a token for a different audience and the Tag History API rejects it with a `403` response.

If you have already set up Docker authentication with [`chainctl auth configure-docker`](https://edu.chainguard.dev/chainguard/chainguard-registry/authenticating/), you can instead read the token from the Docker credential helper:

```shell
auth_header="Authorization: Bearer $(echo 'cgr.dev' | docker-credential-cgr get | jq -r .Secret)"
```

You may use the [`crane` tool](https://github.com/google/go-containerregistry/tree/main/cmd/crane) to get your token instead:
You can also use the [`crane` tool](https://github.com/google/go-containerregistry/tree/main/cmd/crane):

```shell
auth_header="$(crane auth token -H cgr.dev/ORGANIZATION_NAME/IMAGE_NAME)"
Expand All @@ -72,7 +80,7 @@ auth_header="$(crane auth token -H cgr.dev/ORGANIZATION_NAME/IMAGE_NAME)"
Replace `ORGANIZATION_NAME` and `IMAGE_NAME` as required. For example, if your organization is `foo.com` and you're interested in the `chainguard-base` image, you will use the following command:

```shell
auth_header="$(crane auth token -H cgr.dev/foo.com/chainguard-base)
auth_header="$(crane auth token -H cgr.dev/foo.com/chainguard-base)"
```

You should now be ready to call the API, either manually or programmatically.
Expand Down