Docker Hub Tokens Security Guide: Access Tokens, Scopes and Image Secret Hygiene

Docker Hub access tokens decide who can push the images your production clusters pull, and the images themselves are one of the most common places secrets leak. A personal access token with write permission can overwrite a trusted tag in every repository its owner can reach, and a token or API key copied into an image layer is published to anyone who runs docker pull. This guide covers both sides of the problem: how identity, roles and tokens work in Docker Hub, how to choose and scope personal and organisation access tokens, what to log and how to keep credentials out of the images you publish. It is written for platform engineers, DevSecOps teams and the administrators who own a Docker Hub organisation.

Key takeaways

• Use organisation access tokens for automation. OATs belong to the organisation, can be limited to specific repositories and scopes, and survive the departure of the person who created them; personal access tokens do not.
• PAT permissions are account-wide. A PAT has one repository permission that applies to every repository the account can access, so a "Read & Write" PAT for one pipeline can push to all of them.
• Expiry is not on by default. Both PATs and OATs default to "None" (never expire), and the expiry date cannot be changed later, so set 30 or 90 days at creation.
• Deleting a leaked secret from an image does not revoke it. Layers persist in every copy already pulled; revoke and reissue the credential, then rebuild.
• Build secrets belong in secret mounts. Docker's documentation says build arguments and environment variables persist in the final image; use RUN --mount=type=secret instead.

How identity and access work in Docker Hub

Docker Hub has user accounts, organisations that own repositories and teams, and, on Docker Business, companies that group several organisations. People sign in with a password, through SSO, or with a token. Automation should never use a password: once two-factor authentication is turned on or SSO is enforced, the CLI does not accept the account password at all and a token is required.

PATs and OATs compared

PAT permission levels

• Repo Public Read-only (default): view, search and pull public repositories.
• Repo Read-only: adds private repositories the account can access.
• Repo Read & Write: adds push to repositories the account manages.
• Repo Read, Write, Delete: adds deleting images and managing repositories.
• No repository access: for tokens used only for Cloud Sandboxes.

Permissions can be changed while a PAT is active or inactive, but not after it expires. Docker does not let you limit a PAT to a single repository; if a job needs that, it needs an OAT.

Admin roles and privileged access

• Keep owners few: owners control SSO, SCIM and every OAT. Use two or three named owners and grant other administrators a custom role.
• Use teams for repository access: custom roles do not grant pull access to private repositories; team permissions do. Avoid making people editors just so a pipeline under their PAT can push.
• Enforce SSO and 2FA: with SSO enforced, the CLI requires a token, which removes reusable passwords from scripts. Before enforcing, Docker advises ensuring CI/CD pipelines use PATs or OATs instead of passwords.
• Remember the leaver problem: a PAT is tied to its creator. If a pipeline runs on an engineer's PAT, either it breaks when they leave or, worse, the account is kept alive to avoid the break. Move such pipelines to OATs. See the OWASP NHI Top 10 NHI10 Human Use of NHI Guide.

Integrations, API tokens and service accounts

OAT scopes worth knowing

OAT scopes are hierarchical: a more capable scope includes the lesser ones in its set.

Choosing a token for each job

Handling tokens on clients and runners

• Use --password-stdin: it keeps the token out of shell history and logs. Never pass it with -p on the command line.
• Configure a credential store: without one, Docker writes base64-encoded credentials into ~/.docker/config.json, which Docker itself describes as less secure. Set credsStore (osxkeychain, wincred, pass or secretservice) or per-registry credHelpers.
• Clean up ephemeral runners: on self-hosted runners, run docker logout at the end of the job or use a fresh home directory, so the next job cannot read the previous job's config.json.
• Store tokens in a vault: the token is shown once and Docker does not store it. Record owner, purpose, scopes and expiry in your inventory at creation. See the Secrets Management Guide.

Image secret hygiene

Token scoping protects the registry. The other half of the problem is secrets carried inside the images it serves. The Docker Hub Secrets Leak 2025 found 10,456 images uploaded in a single month that exposed keys, most often AI model API keys, through packed .env files, hardcoded source, secrets written directly into Dockerfiles and whole project directories copied into the build. Earlier academic work, summarised in Secrets in Docker Hub Images, found secrets in about 8.5% of 337,171 images, including private keys still used by live TLS and SSH hosts.

Scan the built image, not only the source. In the PyPI Admin GitHub Token Leak 2024, a token that was never committed reached public images through a compiled .pyc file because the .dockerignore did not exclude caches. See the Container Image Security Guide.

Logging and detection

Docker Hub activity logs are available on Team and Business. Docker Home keeps them for 90 days, the UI queries up to 30 days at a time, and the audit logs API returns up to three months of events in requests of up to 31 days. Export them to your SIEM with an OAT that holds only Audit Log Read, because 90 days is shorter than many exposure windows.

Also review the "Last used" column on PAT and OAT lists: tokens unused for 30 days are candidates for deletion, and use of a token outside its pipeline's schedule is worth investigating. Relevant ATT&CK techniques are T1528 Steal Application Access Token, T1552.001 Credentials In Files and T1195.002 Compromise Software Supply Chain.

Metrics that show it is working

• Automation on OATs: percentage of CI/CD and cluster pull credentials that are OATs rather than PATs.
• Expiry coverage: percentage of active tokens with an expiry of 90 days or less (target 100%).
• Least scope: number of OATs with "all organisation repositories" or Image Delete, trending down.
• Stale tokens: count of tokens not used in 30 days.
• Image secret findings: secrets detected in built images per month, and the share revoked (not just removed) within 24 hours.
• Log export continuity: days of activity log history held outside Docker Hub.

Hardening baseline

1. Inventory: list every PAT and OAT, its creator, scopes, expiry and last used date, and map each to the pipeline or person that uses it.
2. Enforce identity controls: turn on 2FA for all members and, on Business, configure and enforce SSO after confirming pipelines use tokens.
3. Pilot OATs: move one service's build and pull credentials to OATs scoped to its repository, run for a release cycle, then revoke the old PAT. Keep the PAT deactivated (not deleted) for a week as a rollback path.
4. Migrate by risk: production image pushes first, then cluster pull secrets, then everything else.
5. Set expiry and rotation: 90 days or less for every token, with a rotation runbook; because expiry cannot be edited, rotation means creating a new token.
6. Fix the build: adopt secret mounts, multi-stage builds and .dockerignore, and add image secret scanning as a blocking gate before push.
7. Protect tags: enable tag immutability on release repositories and deploy by digest.
8. Stream logs: export activity logs to the SIEM and alert on the events above.

Framework mapping

Common misconfigurations

• Pipelines on a person's PAT: the token carries that person's access to every repository and dies, or lingers, with their account.
• Never-expiring tokens: "None" is the default for both token types. Tokens created years ago with Read, Write, Delete remain valid until someone deletes them.
• "All organisation repositories" on a pull secret: one leaked cluster secret then exposes every private image, and any secrets inside them.
• Removing the image, keeping the key: in the Flare study about a quarter of developers removed a leaked secret within a day or two, but most did not revoke it, so anyone who had pulled the image could still use it.
• Plain-text config.json on shared runners: without a credential store, a token sits base64-encoded on disk for the next job or any malware on the host.
• Short log retention: relying on 90 days of in-product history means a token leaked longer ago cannot be investigated, as PyPI found when GitHub's 90-day security log limit left the start of a 15-month image exposure unexplained.

Practitioner checklist

• Inventory every PAT and OAT with owner, scopes, expiry and last used date.
• Move CI/CD and cluster pull credentials from PATs to OATs scoped to named repositories.
• Set an expiry of 90 days or less on every new token and delete tokens unused for 30 days.
• Limit owners, use custom roles for token administration and teams for repository access.
• Enforce 2FA and, on Business, SSO once pipelines no longer use passwords.
• Configure credential stores and use --password-stdin on every client and runner.
• Use secret mounts, multi-stage builds and .dockerignore, and scan built images before push.
• Revoke and reissue any credential found in an image, then rebuild and republish.
• Export activity logs to the SIEM and alert on token changes, privacy changes and deletions.

Standards and references

• Docker Docs: Access tokens
• Docker Docs: Organization access tokens
• Docker Docs: Access token permissions and scopes reference
• Docker Docs: Core roles and permissions
• Docker Docs: Activity logs
• Docker Docs: Build secrets
• Docker Docs: docker login reference
• MITRE ATT&CK: T1552.001 Credentials In Files

Related NHI Mgmt Group resources: Container Registry Security Guide · Container Image Security Guide · npm Tokens Security Guide · Kubernetes NHI Security Guide · API Key Management Guide