Organization access tokens

Organization access tokens (OATs) provide secure, programmatic access to Docker Hub for automated systems, CI/CD pipelines, and other business-critical tasks. Unlike personal access tokens tied to individual users, OATs are associated with your organization and can be managed by any organization owner.

Warning

Organization access tokens are incompatible with Docker Desktop and Image Access Management. If you use these features, use personal access tokens instead.

Who should use organization access tokens?

Use OATs for automated systems that need Docker Hub access without depending on individual user accounts:

• CI/CD pipelines: Build and deployment systems that push and pull images
• Production systems: Applications that pull images during deployment
• Monitoring tools: Systems that need to check repository status or pull images
• Backup systems: Tools that periodically pull images for archival
• Integration services: Third-party tools that integrate with your Docker Hub repositories

Key benefits

Benefits of using organization access tokens include:

• Organizational ownership: Not tied to individual users who might leave the company
• Shared management: All organization owners can create and manage OATs
• Separate usage limits: OATs have their own Docker Hub rate limits, not counting against personal accounts
• Better security audit: Track when tokens were last used and identify suspicious activity
• Granular permissions: Limit access to specific repositories and operations

Prerequisites

To create and use organization access tokens, you must have:

• A Docker Team or Business subscription
• Owner permissions
• Repositories you want to grant access to

Create an organization access token

Owners can create tokens with these limits:

• Team subscription: Up to 10 OATs per organization
• Business subscription: Up to 100 OATs per organization

Expired tokens count toward your total limit.

To create an OAT:

1. Sign in to Docker Home and select your organization.
2. Select Identity & auth, then Access tokens.
3. Select Generate access token.
4. Configure token details:
   • Label: Descriptive name indicating the token's purpose
   • Description (optional): Additional details
   • Expiration date: When the token should expire
5. Expand the Repository drop-down to set per-repository access permissions:
   • Optional. Select Read public repositories for access to public repositories.
   • Select Add repository and choose a repository from the drop-down.
   • Set the permission level for each repository. Available scopes range from pulling and pushing images to managing tags, webhooks, repository groups, and immutable tag settings. See Repository scopes for the full list.
   • Add up to 50 repositories as needed.
6. Optional. Configure organization-level permissions by expanding the Organization drop-down and selecting Allow management access to this organization's resources:
   • Member Edit: Edit members of the organization
   • Member Read: Read members of the organization
   • Invite Edit: Invite members to the organization
   • Invite Read: Read invites to the organization
   • Group Edit: Edit groups of the organization
   • Group Read: Read groups of the organization
   • Repository List: List all repositories, including private ones (scope-repository-list)
   • Repository Create: Create new repositories (scope-repository-create)
   • Registry Usage Read: Read namespace-level registry usage metrics (scope-registry-usage-read)
7. Select Generate token. Copy the token that appears on the screen and save it. You won't be able to retrieve the token once you exit the screen.

Important

Treat organization access tokens like passwords. Store them securely in a credential manager and never commit them to source code repositories.

Use organization access tokens

Sign in to the Docker CLI using your organization access token:

$ docker login --username <YOUR_ORGANIZATION_NAME>
Password: [paste your OAT here]

When prompted for a password, enter your organization access token.

Modify existing tokens

To manage existing tokens:

1. Sign in to Docker Home and select your organization.
2. Select Identity & auth, then Access tokens.
3. Select the actions menu in the token row, you can:
   • Edit
   • Deactivate
   • Delete
4. Select Save after making changes to a token.

Available scopes

Scopes control what an OAT can do. Repository-level scopes are assigned per repository when you create the token. Organization-level scopes apply to the whole organization.

Higher scopes include the permissions of lower ones where noted.

Repository scopes

Organization scopes

Creating a repository requires the organization-level scope-repository-create permission. No repository-level scope, including admin scopes on existing repositories, grants this permission.

Hub API support

OATs can authenticate requests to most Docker Hub API endpoints under /v2/namespaces/{namespace}/repositories/. Pass the token as a Bearer token in the Authorization header with your organization name as the username.

Supported endpoints

The following endpoint categories accept OAT authentication:

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

Listing behavior

GET /v2/namespaces/{namespace}/repositories returns results based on the token's configured scopes:

• With scope-repository-list scope (or equivalent): all repositories are returned, including private ones.
• Without that scope: only public repositories are returned.

This filtering is silent: the response is a normal 200, with no error or indicator that private repositories were withheld.

Unsupported legacy endpoints

OATs only authenticate requests to the namespace-scoped routes documented above. The following legacy repository paths are OAT unsupported and reject every OAT with 403 token issued from organization access token is not allowed, regardless of the token's scopes. Use the linked replacement endpoints instead:

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

Organization access token best practices

• Regular token rotation: Set reasonable expiration dates and rotate tokens regularly to minimize security risks.
• Principle of least privilege: Grant only the minimum repository access and permissions needed for each use case.
• Monitor token usage: Regularly review when tokens were last used to identify unused or suspicious tokens.
• Secure storage: Store tokens in secure credential management systems, never in plain text or source code.
• Immediate revocation: Deactivate or delete tokens immediately if they're compromised or no longer needed.