# How to rotate Docker Hub access tokens

> Reissue a Docker Hub personal or organization access token: generate the new one, log every runner in again, then deactivate and delete the old token.

URL: https://crunu.com/rotate/docker-hub
Language: en
Updated: 2026-10-30

Generate a new personal access token in Docker Home with the same repository permission as the old one, log in with it on every runner and server that pulls or pushes images, check that both work, then deactivate the old token and delete it after a quiet period. Tokens are independent, so the old and the new one work side by side. Deactivation is the safe first stop: a deactivated token stops working until you activate it again ([Docker docs](https://docs.docker.com/security/access-tokens/personal-access-tokens/)).

Crunu doesn't create, deactivate or delete Docker Hub tokens; it has no Docker Hub integration. It tells you which Docker values a departing person could read, keeps the replacement as a new environment version, and hands it to `docker login` on the machines that need it.

*Figure: Timeline of rotating the Personal access token. Step 1: a new key is issued while the old one keeps working. Step 2: every place that uses the key is updated, with no downtime because both keys work. Step 3: the old key is revoked. After revocation the old key stops working at once.*

## Personal or organization token

**Personal access tokens** belong to one Docker account and start with `dckr_pat_` ([Hub API](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/)). A token carries one repository permission that covers every repository the account can reach ([token reference](https://docs.docker.com/security/access-tokens/reference/)):

- **Repo Public Read-only**, the default: view, search and pull public images.
- **Repo Read-only**: also pull from private repositories you can access.
- **Repo Read & Write**: also push to any repository your account manages.
- **Repo Read, Write, Delete**: also delete images and manage repositories.

You can't limit a personal token to one repository. If two-factor authentication is on or SSO is enforced, the CLI won't take your password, so a personal token is the only way to sign in there.

**Organization access tokens** belong to the organization and start with `dckr_oat_`. They exist on Docker Team and Business, can be created by organization owners, company owners or a custom role with the right permission, and can list up to 50 repositories with separate scopes each ([organization tokens](https://docs.docker.com/enterprise/security/access-tokens/)). Any organization owner can see, edit, deactivate or delete them, and Docker describes them as the choice for automation that must keep working as people join and leave. Team allows up to 10 of them and Business up to 100. They don't work with Docker Desktop.

For CI that pushes images, an organization token limited to the repositories it builds is the smaller target.

## Reissue without downtime

1. Sign in to Docker Home, open your avatar, **Account settings**, **Personal access tokens**, and choose **Generate new token**. Pick the same repository permission and an expiration. Docker shows the token once and doesn't store it.
2. Save it in Crunu as `DOCKERHUB_TOKEN` next to `DOCKERHUB_USERNAME` in the environment your builds use, for example `web-app / staging`. The save becomes a new version in the environment's history.
3. Log in again on each runner and server. `docker login` stores credentials in the configured credential store, or in `config.json` if none is set, so a machine keeps using the old token until it logs in with the new one.
4. Pull a private image and, for a write token, push a test tag to confirm the new login works.
5. Deactivate the old token. If a forgotten machine starts failing, activate it again, log that machine in with the new token, and repeat. Then delete the old token.

```sh
crunu run --env web-app/staging -- sh -c \
  'printf %s "$DOCKERHUB_TOKEN" | docker login --username "$DOCKERHUB_USERNAME" --password-stdin'
```

Docker recommends `--password-stdin` because the value then doesn't end up in shell history or log files ([docker login](https://docs.docker.com/reference/cli/docker/login/)). For an organization token, the username is the organization's name.

## Expiration can't be changed later

The default expiration is **None**, which creates a token that never expires. The alternatives are 30 days, 90 days, or a custom date and hour up to a year ahead, and you can't edit the expiration of an existing token. Expired and revoked tokens can only be deleted. A short expiration is the simplest way to make sure a forgotten token ends on its own.

## When to reissue a Docker Hub token

- **Someone leaves.** Their personal tokens belong to their own Docker account, not to the organization, while organization tokens can be deactivated by any owner. Reissue every token they could read, such as a bot account's personal token or an organization token for CI. In Crunu, removing the person produces a reissue checklist of those values by name.
- **A leak.** Deactivate the token at once and accept failed pulls until the new token is in place; a write token lets whoever holds it push images to your repositories.
- **A schedule.** If the token has no expiration, set your own interval and give the replacement an expiry date.

[What to rotate when a developer leaves](https://crunu.com/guides/developer-offboarding-secret-rotation) covers the order of work for a full departure, and the [offboarding checklist](https://crunu.com/tools/offboarding-checklist) builds the list for your stack. Tokens are generated and removed in Docker Home; Crunu records when the new value was saved and by whom.

## FAQ

### Can a Docker Hub token be limited to one repository?

A personal access token can't: its repository permission covers every repository your account can reach. An organization access token can list up to 50 repositories, each with its own scopes, but it needs a Docker Team or Business subscription.

### What is the difference between deactivating and deleting a token?

A deactivated token stops working until you activate it again, so it is a safe first step. Deleting removes it for good. Expired and revoked tokens can only be deleted, and for organization tokens they count toward the limit until you do.

### Do Docker Hub access tokens expire?

Only if you set it up that way. The default expiration is None, which creates a token that doesn't expire. You can pick 30 days, 90 days or a custom date up to a year ahead, and you can't change it after creation.

### Does Crunu rotate Docker Hub tokens?

No. Crunu doesn't call Docker Hub. It shows which Docker values a departing person received, stores the new token as a new environment version and feeds it to docker login through crunu run.

## Sources

- [Docker Docs: Personal access tokens](https://docs.docker.com/security/access-tokens/personal-access-tokens/) (accessed 2026-10-30)
- [Docker Docs: Organization access tokens](https://docs.docker.com/enterprise/security/access-tokens/) (accessed 2026-10-30)
- [Docker Docs: Access token reference](https://docs.docker.com/security/access-tokens/reference/) (accessed 2026-10-30)
- [Docker Docs: docker login](https://docs.docker.com/reference/cli/docker/login/) (accessed 2026-10-30)
- [Docker Hub API: Create access token](https://docs.docker.com/reference/api/hub/latest/operations/AuthCreateAccessToken/) (accessed 2026-10-30)