Access tokens

A registry token is the password half of a registry login. The username is always your Registry Namespace, never your email address.

Create tokens in the portal under Container Registry → Access Tokens.

The token is shown once

When a token is created the portal shows it with Save this token now. It will not be shown again., along with ready-made Docker, Podman and CI snippets. There is no way to read the value back afterwards. If you lose it, delete the token and create a new one.

What a token can reach

Repository Scope does not restrict anything

The create dialog has a Repository Scope field, hinted Leave empty for access to all repositories. Whatever you type there is stored and shown in the Scopes column, but it does not narrow what the token can do. Every token reads and writes every repository under your Registry Namespace, including repositories created later. Treat each token as full access to the whole registry, and use separate tokens only so that you can revoke them separately.

Leave Expiry empty

Picking a date in the Expiry field makes the request fail and no token is created. Create tokens without an expiry and revoke them by deleting them.

Logging in

echo '<token>' | docker login registry.itsh.dev -u <your-slug> --password-stdin

Podman takes the same arguments:

echo '<token>' | podman login registry.itsh.dev -u <your-slug> --password-stdin

Pass the token on stdin rather than with -p. A token given on the command line ends up in your shell history and in the process list of whatever machine ran it, and it cannot be narrowed afterwards.

In CI, put the token in the platform's secret store and reference it there. The portal's CI/CD tab on the token dialog shows the variable names for the common systems.

The token behind your pull secrets

Provisioning a Kubernetes namespace creates a registry token named k8s-pull-secret and uses it for the itsh-registry pull secret in that namespace. It shows up in the token list like any other token, and deleting it stops the pods in that namespace from pulling. See Images and pull secrets for how that secret is used and what to do if a namespace does not have one.

How many, and revoking

An account can hold 10 tokens at a time, counting the k8s-pull-secret tokens created for your namespaces. Creating another one fails until you delete some.

Deleting a token takes effect on the next login. Credentials already handed out to a running client stay usable for up to 5 minutes, which is how long the registry's short-lived session tokens are valid. To cut a leaked token off completely, delete it and then re-pull or restart anything that was using it.

When login fails

A wrong username or a token that no longer exists gives you this, with an empty reason after the colon:

Error response from daemon: Get "https://registry.itsh.dev/v2/": unauthorized:

In order of likelihood: the username is not the Registry Namespace, the token was deleted or mistyped, or the registry is not enabled on the account. The same message appears when the registry has been suspended.

A login that works while a push is refused is a different problem: the registry is over its storage cap, which blocks writes and leaves reads alone. See Storage and cleanup.

What's next

• Storage and cleanup for what happens when the cap is reached
• Container registry for the Registry Namespace and a first push