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

A token only ever reaches repositories under your own Registry Namespace. The Repository Scope field on the create dialog narrows that further:

• Left empty, the token reaches every repository under your Registry Namespace, including repositories created later. The Scopes column shows All repositories.
• With comma-separated names, the token reaches those repositories and the ones nested below them, nothing else. my-app covers registry.itsh.dev/<your-slug>/my-app and registry.itsh.dev/<your-slug>/my-app/worker.

A scope matches whole path segments

my-app does not cover my-app-v2. A pipeline that pushes several images needs each of them listed, or a shared parent such as my-app with the images below it as my-app/api and my-app/web.

Enter the names without the <your-slug>/ prefix, the way the portal lists them under Repositories. A pasted prefix is removed. Names follow the registry's own rules: lowercase letters and digits, separated by ., _ or -, with / between path segments. Anything else is refused and no token is created.

A push or pull outside the scope is rejected as unauthorized, the same as a path under someone else's Registry Namespace. The scope cannot be edited afterwards: create a new token and delete the old one.

Give CI pipelines, contractors and other third parties a token scoped to the repositories they actually build or deploy, so that a leaked token exposes those and nothing else.

A date in the Expiry field makes the token stop working at the end of that day, in your browser's time zone. Logins with it are then refused like those with a deleted token. The token stays in the list, and counts towards the limit, until you delete it. Left empty, the token does not expire.

Pull-only tokens

Ticking Pull only on the create dialog makes a token that can only pull. Push and delete are refused, in every repository its scope covers. The Scopes column marks it Pull only.

Use one wherever images are deployed but never built:

• Kubernetes clusters and other deploy targets that pull your images
• Third parties that deploy your images without building them

The setting cannot be changed after creation. To switch a token to pull-only or back, create a new token and delete the old one.

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, mistyped or has expired, 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. Either the token is pull-only, or 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