Access token reference

Look up what an access token is allowed to do. You choose a permission or a set of scopes when you create the token.

Personal access token permissions

Each personal access token (PAT) has one permission level that you select when you create the token. The token applies to every repository your account can access. You can't limit a token to a single repository.

• Repo Public Read-only: View, search, and pull images from public repositories. This is the default.
• Repo Read-only: View, search, and pull images from public repositories and from private repositories you have access to.
• Repo Read & Write: Everything in Repo Read-only, plus push images to any repository your account manages.
• Repo Read, Write, Delete: Everything in Repo Read & Write, plus delete images and manage your repositories.
• Cloud Sandboxes: Authenticate to the Docker Cloud Sandboxes API. Cloud Sandboxes is a paid feature.

Choose the lowest permission that covers what the token needs to do. For example, a CI job that only pulls a private base image needs Repo Read-only. You can change PAT permissions at any time if the PAT is active or inactive, but not expired.

Organization access token scopes

Scopes control what an organization access token (OAT) can do. You choose them when you create or edit the token. In Docker Home, each scope shows its name and a short description while the value in the table is what the token carries. You can change OAT scopes at any time if the OAT is active or inactive, but not expired.

Within a related set of operations, selecting a more capable scope also grants the less capable ones. For example:

• Image Delete includes Image Push
• Image Push includes Image Pull

If you select Image Delete, you don't need to select the other two. The Grants column notes each inclusion.

Repository scopes

Repository scopes apply to each repository you add, or to all repositories in the organization if you select All <organization> repositories.

Organization scopes

Organization scopes apply to the whole organization.

Creating a repository requires the organization-level Repository Create scope. No repository scope grants it, not even Repository Admin on an existing repository.

Product scopes

These sections appear alongside Repository and Organization in the token's resources.

Docker Hub API

An OAT can authenticate most Docker Hub API endpoints under /v2/namespaces/{namespace}/repositories/. First create an OAT, then exchange it for a short-lived bearer token with the Create access token API. Use your organization name as the identifier and the OAT as the secret:

$ TOKEN=$(curl -s -X POST "https://hub.docker.com/v2/auth/token" \
    -H "Content-Type: application/json" \
    -d '{"identifier": "<YOUR_ORGANIZATION_NAME>", "secret": "<YOUR_OAT>"}' \
    | jq -r .access_token)

Pass the bearer token in the Authorization header:

$ curl -s -H "Authorization: Bearer $TOKEN" \
    "https://hub.docker.com/v2/namespaces/<YOUR_ORGANIZATION_NAME>/repositories"

Supported endpoints

The following endpoint groups accept OAT authentication:

• Repositories: list, create, get, update, and delete
• Tags: list, get, and delete; get tag images, attestations, and compose files
• Dockerfile: get and update a repository's linked Dockerfile
• Repository groups: list, get, create, update, and delete assignments
• Stars: list, count, add, and remove
• Immutable tags: update and verify policies
• Repository categories, privacy, and webhook pipeline settings
• Namespace metrics

Listing behavior

GET /v2/namespaces/{namespace}/repositories filters results by the token's scopes:

• With Repository List (scope-repository-list), the response includes every repository, including private ones.
• Without it, the response includes only public repositories.

The filtering is silent. The response is a normal 200 with no indication that private repositories were left out.

Unsupported legacy endpoints

OATs only work with the namespace-scoped routes described above. The following legacy paths reject every OAT, regardless of its scopes, with 403 token issued from organization access token is not allowed. Use the replacement endpoint instead:

• GET /v2/repositories/{namespace}/{repository}: use Get repository
• GET /v2/repositories/{namespace}: use List repositories
• GET /v2/users/{username}/repositories: use List repositories

Next steps

• Create a PAT
• Create an OAT
• Choose a PAT or OAT