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

A personal access token (PAT) has two separate access settings: repository permissions and Cloud Sandboxes access. You set both when you create the token. Select at least one permission.

Repository permissions

The repository permission applies to every repository your account can access. You can't limit a token to a single repository. Select No repository access when the token should not access repositories.

• 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.

Choose the lowest repository 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.

Cloud Sandboxes access

Cloud Sandboxes access is separate from the repository permission.

• Allow Cloud Sandboxes access: Select this in Docker Home to let the token create and use Docker Cloud Sandboxes. You can add it to any repository permission in the list, or use it with No repository access.
• sandbox:use: The scope a PAT needs to authenticate to Cloud Sandboxes. Selecting Allow Cloud Sandboxes access adds this scope to the token. See Cloud Sandboxes authentication.

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