10.1.2.2 Registry Access Tokens

Registry access tokens are scoped, independently revocable credentials used in place of an account's actual password for authenticating with a registry, providing finer-grained control and reduced exposure risk compared to using a primary account password directly.

Generating an Access Token

Most registries provide a way to generate a token through their web interface or API, typically allowing the token's permissions to be scoped to specific actions.

docker login registry.example.com -u myuser

Password: <paste generated access token here>

Providing a generated token at this prompt, rather than the account's actual password, authenticates using that scoped, independently manageable credential instead.

Why Scoped Permissions Matter

A token generated specifically for, say, pulling images from one particular repository carries less risk if compromised than a credential with full account access, since its potential misuse is limited to whatever narrow scope it was actually granted.

Token scope: read-only, repository: myteam/myapi

A token scoped this narrowly can only pull from this specific repository, unable to push, delete, or access anything else even if somehow exposed.

Revoking a Compromised or No-Longer-Needed Token

An access token can be individually revoked without affecting the underlying account's password or any other tokens, providing precise control over credential lifecycle.

docker login registry.example.com

Following revocation, any system still attempting to authenticate with the revoked token fails, without requiring a broader, account-wide password change.

Why Registry Access Tokens Matter

Using scoped, individually revocable access tokens rather than an account's actual password is a meaningfully safer practice for registry authentication, particularly important for automated systems where credentials are stored and used programmatically, often with a broader potential exposure surface than direct, manual interactive logins.