1
0
mirror of https://github.com/docker/docs.git synced 2026-10-28 07:15:09 +03:00

docs: refresh access token guidance and SSO FAQs (#26252)

Refreshing access tokens docs

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Alexa Kristensen
2026-10-09 08:21:31 -05:00
committed by GitHub
parent 63cc3634e3
commit e486cdf46b
8 changed files with 494 additions and 241 deletions

View File

@@ -23,6 +23,9 @@ keywords:
- convert Docker account
- sign in after convert
- organization owner
- personal access token
- auto-generated token
- incorrect authentication credentials
tags: [FAQ]
toc_max: 2
aliases:
@@ -80,6 +83,46 @@ If you have a trademark for your Docker ID,
[Docker Support](https://hub.docker.com/support/contact/) can retrieve the
Docker ID for you.
### Why did one of my personal access tokens disappear?
Signing in to Docker Desktop creates an auto-generated personal access
token for CLI authentication. An account can have five of these tokens.
When Docker Desktop creates another one, it deletes the least recently
used auto-generated token. A token that has never been used is ranked
by when it was created. The deleted token is removed from your token
list.
Tokens you create yourself are not deleted this way. They stay in the
list until you delete them. A revoked token stays in the list with a
status of **Revoked**.
For how these tokens are created and how to tell them apart, see
[Auto-generated PATs](/manuals/security/access-tokens/personal-access-tokens.md#auto-generated-tokens).
### Why does sign-in fail with "Incorrect authentication credentials"?
`docker login` returns `Incorrect authentication credentials` when the
username and secret don't match a credential that can sign in. The
message is the same when a personal access token is wrong, expired,
inactive, or revoked, and when the username is not the account that
owns the token.
Check the following:
1. The username is the Docker ID of the account that owns the token.
Use an organization name only with an
[organization access token](/manuals/security/access-tokens/organization-access-tokens.md).
2. You pasted the full token, with no spaces or line breaks. Docker
shows a token only once. If you no longer have it,
[create a new personal access token](/manuals/security/access-tokens/personal-access-tokens.md#create-a-personal-access-token).
3. On the **Personal access tokens** page, find the token and use its
status:
- **Expired:** Create a new token. You can't change the expiration
date.
- **Inactive:** Select **Activate**.
- **Revoked:** The token can't be used again. Delete it and create
a new one.
## Organizations
### What's an organization name or namespace?

View File

@@ -145,7 +145,7 @@ Yes, you can convert existing users to SSO accounts. Ensure users have:
- Company domain email addresses and accounts in your IdP
- Docker Desktop version 4.4.2 or later
- Personal access tokens created to replace passwords for CLI access
- CI/CD pipelines updated to use PATs instead of passwords
- CI/CD pipelines updated to use [PATs or OATs](/manuals/security/access-tokens/_index.md) instead of passwords, or an [OIDC connection](/manuals/security/authentication/oidc-connections/_index.md) for GitHub Actions
For detailed instructions, see [Configure single sign-on](/manuals/security/authentication/single-sign-on/connect.md).
@@ -196,13 +196,13 @@ replace users' full names.
### Does Docker SSO support authenticating through the command line?
When SSO is enforced, [passwords are prevented from accessing the Docker CLI](/manuals/security/security-announcements.md#deprecation-of-password-logins-on-cli-when-sso-enforced). You must use a personal access token (PAT) for CLI authentication instead.
When SSO is enforced, [passwords are prevented from accessing the Docker CLI](/manuals/security/security-announcements.md#deprecation-of-password-logins-on-cli-when-sso-enforced). Each user must sign in with a [personal access token (PAT)](/manuals/security/access-tokens/personal-access-tokens.md). Users who already used a PAT before SSO enforcement can continue using that PAT.
Each user must create a PAT to access the CLI. To learn how to create a PAT, see [Manage personal access tokens](/manuals/security/access-tokens/personal-access-tokens.md). Users who already used a PAT before SSO enforcement can continue using that PAT.
For CI/CD and other automation, use an [organization access token (OAT)](/manuals/security/access-tokens/organization-access-tokens.md) or a PAT. For GitHub Actions, you can use an [OIDC connection](/manuals/security/authentication/oidc-connections/_index.md) instead of storing a long-lived token. See [Access tokens](/manuals/security/access-tokens/_index.md).
### How does SSO affect automation systems and CI/CD pipelines?
Before enforcing SSO, you must [create personal access tokens](/manuals/security/access-tokens/personal-access-tokens.md) to replace passwords in automation systems and CI/CD pipelines.
Before enforcing SSO, replace passwords in automation and CI/CD with an access token. Prefer an [organization access token (OAT)](/manuals/security/access-tokens/organization-access-tokens.md) for pipelines owned by the organization. Use a [personal access token (PAT)](/manuals/security/access-tokens/personal-access-tokens.md) when the job should run as a person. For GitHub Actions, you can use an [OIDC connection](/manuals/security/authentication/oidc-connections/_index.md) instead of storing a long-lived token.
### Can I turn on SSO without enforcing it immediately?

View File

@@ -305,7 +305,7 @@ and subscriptions.
### New
- [Organization access tokens](/manuals/security/access-tokens/organization-access-tokens.md#available-scopes)
- [Organization access tokens](/manuals/security/access-tokens/reference.md#organization-access-token-scopes)
now include repository scopes and organization management scopes for members,
invites, and groups.

View File

@@ -1,8 +1,12 @@
---
title: Access tokens
linkTitle: Access tokens
description: Create and manage personal and organization access tokens for Docker Hub authentication.
keywords: access tokens, personal access tokens, organization access tokens, PAT, OAT, Docker security
description: >-
Choose a personal or organization access token to authenticate to
Docker Hub.
keywords: >-
access tokens, personal access tokens, organization access tokens,
PAT, OAT, Docker Hub, Docker security
weight: 10
grid:
- title: Personal access tokens
@@ -13,22 +17,60 @@ grid:
description: Grant org-owned Hub access to CI/CD and other automation.
icon: building-office-2
link: /security/access-tokens/organization-access-tokens/
- title: Reference
description: Look up PAT permissions, OAT scopes, and Hub API support.
icon: list-bullet
link: /security/access-tokens/reference/
---
Access tokens let you authenticate to Docker Hub without using your password.
Use a token for the Docker CLI, automation, and any account that has
two-factor authentication (2FA) or enforced single sign-on (SSO), because
password sign-in to the CLI is not supported in those cases.
Access tokens authenticate to Docker Hub in place of a password. Docker
Hub offers two types: personal access tokens (PATs), tied to your
account, and organization access tokens (OATs), owned by an
organization. Both work with `docker login` and in automation, and you
can deactivate or delete a token at any time without changing a
password.
## Choose a token type
| Token | Ownership | Use when | Limitations |
| --- | --- | --- | --- |
| Personal access token (PAT) | Tied to an individual Docker account | CLI access, local tools, and automation that should run as you. Required for CLI sign-in when 2FA is on or SSO is enforced | Access ends if the account leaves the organization or the token is revoked |
| Organization access token (OAT) | Owned by the organization. Any organization owner can manage it | CI/CD and other automation that must keep working when membership changes | Incompatible with Docker Desktop and Image Access Management |
## PATs
For GitHub Actions, [OIDC connections](/manuals/security/authentication/oidc-connections/_index.md)
are an alternative to storing a long-lived organization access token.
Use a PAT for Docker Desktop, for environments governed by
[Image Access Management](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md),
and for other tools that run as you. A PAT is also required to sign in
to the CLI when two-factor authentication (2FA) is turned on or single
sign-on (SSO) is enforced, because the CLI doesn't accept your password
in those cases.
A PAT uses
[one permission level](/manuals/security/access-tokens/reference.md#personal-access-token-permissions)
for every repository the account can access.
## OATs
Use an OAT for production systems that pull images during deployment,
monitoring or backup tools that check repository status or pull images,
third-party services that integrate with your repositories, and scripts
that call the
[Docker Hub API](/manuals/security/access-tokens/reference.md#docker-hub-api).
OATs don't work with Docker Desktop or Image Access Management.
An OAT can be limited to specific repositories and operations, and it
has its own Docker Hub usage limits, separate from individual accounts.
To see scopes, see
[Access token reference](/manuals/security/access-tokens/reference.md).
## OIDC connections
If your automation runs in GitHub Actions, you don't need to store a token.
An [OIDC connection](/manuals/security/authentication/oidc-connections/_index.md)
lets a workflow exchange GitHub's short-lived identity token for Docker
access on each run, so there is no long-lived credential to rotate,
scope, or leak. Organization owners set up OIDC connections, and they
require a Docker Team or Docker Business subscription.
Use an OAT instead when the automation runs outside GitHub Actions, or
when you need a credential that works with `docker login` from any
system.
## Next steps

View File

@@ -1,206 +1,147 @@
---
title: Organization access tokens
title: Create and manage organization access tokens
linkTitle: Organization access tokens
description: Create and manage organization access tokens to securely authenticate automated systems and CI/CD pipelines with Docker Hub
keywords: organization access tokens, OAT, docker hub security, programmatic access, automation
description: >-
Create an organization access token, choose its repository and
organization scopes, and use it in CI/CD and the Docker Hub API.
keywords: >-
organization access token, OAT, Docker Hub, CI/CD authentication,
docker login, token scopes, repository permissions, Docker Hub API,
automation, Docker Team, Docker Business
weight: 20
aliases:
- /security/for-admins/access-tokens/
- /enterprise/security/access-tokens/
- /security/for-admins/access-tokens/
- /enterprise/security/access-tokens/
---
{{< summary-bar feature_name="OATs" >}}
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.
An organization access token (OAT) lets automated systems sign in to
Docker Hub as your organization instead of as a person. Use an OAT for
CI/CD pipelines, deployment jobs, and other automation that must keep
working when people join or leave the organization.
Unlike a personal access token (PAT), an OAT belongs to the
organization. Any organization owner can see, edit, deactivate, or
delete it. Each token has its own scopes, so it can only reach the
repositories and organization settings you choose.
> [!WARNING]
>
> Organization access tokens are incompatible with Docker Desktop and Image Access Management. If you use these features, use [personal access tokens](/manuals/security/access-tokens/personal-access-tokens.md) instead.
> OATs don't work with Docker Desktop or Image Access Management. For
> those features, use
> [PATs](/manuals/security/access-tokens/personal-access-tokens.md) instead.
## Who should use organization access tokens?
## Best practices
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
- Set an expiration date and rotate tokens on a schedule
- Grant only the repositories and scopes each job needs
- Review the **Last used** column to find unused or suspicious tokens
- Store tokens in a credential manager, never in plain text or source
code
- Deactivate or delete a token as soon as it's compromised or no longer
needed
## Prerequisites
To create and use organization access tokens, you must have:
To create and manage OATs, you need:
- A Docker Team or Business subscription
- Owner permissions
- Repositories you want to grant access to
- A Docker Team or Docker Business subscription
- One of these roles in the organization:
- Organization owner
- Company owner, for organizations that belong to a company
- A [custom role](/manuals/security/roles-and-permissions/custom-roles/permissions-reference.md)
that includes the **Manage organization access tokens** permission
## 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.
> [!IMPORTANT]
>
> Treat access tokens like passwords and keep them secure. Store tokens
> in a credential manager and never commit them to source code.
To create an OAT:
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization.
organization.
1. Select **Identity & auth**, then **Access tokens**.
1. Select **Generate access token**.
1. Configure token details:
- Label: Descriptive name indicating the token's purpose
- Description (optional): Additional details
- Expiration date: When the token should expire
1. 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](#repository-scopes)
for the full list.
- Add up to 50 repositories as needed.
1. 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`)
1. 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.
1. Configure the token:
- **Label:** A name that describes what the token is for. This field
is required.
- **Access token description:** Optional. Up to 200 characters.
- **Expiration date:** Select **30 days**, **90 days**, or
**Custom**. With **Custom**, choose a date and time up to one year
from today. The default, **None**, creates a token that doesn't
expire. You can't change the expiration date after you create the
token.
1. In **Resources**, expand **Repository** to choose which repositories
the token can reach:
- Optional. Select **Read public repositories** to let the token pull
from any public repository.
- Select **Add repository**, then choose a repository or
**All `<organization>` repositories** from the drop-down.
- Select one or more scopes for that repository. See
[Repository scopes](/manuals/security/access-tokens/reference.md#repository-scopes).
- Repeat for up to 50 repositories. Each repository has its own
scopes.
1. Optional. Expand **Organization** and select the organization-level
scopes the token needs, such as reading members or creating
repositories. See
[Organization scopes](/manuals/security/access-tokens/reference.md#organization-scopes).
1. Optional. Expand **Docker Build Cloud** or **Docker Governance** to
grant access to those products. See
[Product scopes](/manuals/security/access-tokens/reference.md#product-scopes).
1. Select **Generate token**. Copy the token and save it. Docker shows
the token once and doesn't store it. You can't retrieve it after you
leave the page.
> [!IMPORTANT]
>
> Treat organization access tokens like passwords. Store them securely in a credential manager and never commit them to source code repositories.
## Sign in
## Use organization access tokens
Sign in to the Docker CLI using your organization access token:
Run `docker login` with your organization name as the username. When
the CLI asks for a password, paste the OAT.
```console
$ docker login --username <YOUR_ORGANIZATION_NAME>
Password: [paste your OAT here]
```
When prompted for a password, enter your organization access token.
## Update, deactivate, or delete
## Modify existing tokens
To manage existing tokens:
You can rename a token, change its description or scopes, deactivate
it, activate it again, or delete it.
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization.
organization.
1. Select **Identity & auth**, then **Access tokens**.
1. Select the actions menu in the token row, you can:
- **Edit**
- **Deactivate**
- **Delete**
1. Select **Save** after making changes to a token.
## Available scopes
The list shows each token's label, status, who created it, when it
was created, when it was last used, and when it expires.
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.
1. Select the actions menu at the end of a token row, then select
**Deactivate**, **Activate**, **Edit**, or **Delete**.
Higher scopes include the permissions of lower ones where noted.
A deactivated token stops working until you activate it again.
Expired tokens can only be deleted. Deleting a token is permanent.
### Repository scopes
1. If you selected **Edit**, change the label, description, or
resources, then select **Update token**.
| Scope | Description | Includes |
|---|---|---|
| `scope-image-pull` | Pull images from the registry | — |
| `scope-image-push` | Push images to the registry | `scope-image-pull` |
| `scope-image-delete` | Delete images and tags via registry endpoints | `scope-image-push` |
| `scope-repository-read` | Read repository metadata, Dockerfile, and stars | — |
| `scope-repository-edit` | Edit repository privacy, categories, Dockerfile, description, and stars | `scope-repository-read` |
| `scope-repository-admin` | Delete the repository | `scope-repository-edit` |
| `scope-tag-read` | List and read tags, image lists, attestations, and compose files | — |
| `scope-tag-admin` | Delete tags | `scope-tag-read` |
| `scope-webhook-read` | List webhook pipelines and delivery history | — |
| `scope-webhook-edit` | Create webhook pipelines | `scope-webhook-read` |
| `scope-webhook-admin` | Delete webhook pipelines | `scope-webhook-edit` |
| `scope-repo-group-read` | List and read repository group assignments | — |
| `scope-repo-group-edit` | Create and update repository group assignments | `scope-repo-group-read` |
| `scope-repo-group-admin` | Delete repository group assignments | `scope-repo-group-edit` |
| `scope-repository-settings-admin` | Configure immutable tag rules | — |
## Token limits
### Organization scopes
Each organization can have a limited number of tokens:
| Scope | Description |
|---|---|
| `scope-repository-list` | List all repositories in the namespace, including private ones |
| `scope-repository-create` | Create new repositories |
| `scope-registry-usage-read` | Read namespace-level registry usage metrics |
- Docker Team: Up to 10 tokens
- Docker Business: Up to 100 tokens
Creating a repository requires the organization-level `scope-repository-create`
permission. No repository-level scope, including admin scopes on existing
repositories, grants this permission.
Expired and deactivated tokens count toward the limit until you delete
them. When you reach the limit, the **Generate access token** button is
disabled until you delete a token.
## Hub API support
## Next steps
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](/reference/api/hub/latest/operations/GetRepository/).
- `GET /v2/repositories/{namespace}` — use
[List repositories](/reference/api/hub/latest/operations/listNamespaceRepositories/).
- `GET /v2/users/{username}/repositories` — use
[List repositories](/reference/api/hub/latest/operations/listNamespaceRepositories/).
## 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.
- [Choose a PAT or OAT](/manuals/security/access-tokens/_index.md)
- [Look up scopes and Docker Hub API support](/manuals/security/access-tokens/reference.md)
- [Create a PAT](/manuals/security/access-tokens/personal-access-tokens.md)
- [Set up OIDC connections for GitHub Actions](/manuals/security/authentication/oidc-connections/_index.md)
- [Review custom role permissions](/manuals/security/roles-and-permissions/custom-roles/permissions-reference.md)

View File

@@ -1,108 +1,140 @@
---
title: Personal access tokens
title: Create and manage personal access tokens
linkTitle: Personal access tokens
description: Create and manage personal Docker access tokens for secure CLI authentication and automation
keywords: personal access tokens, PAT, docker cli authentication, docker hub security, programmatic access
description: >-
Create a personal access token, set its permissions and expiration,
and sign in to the Docker CLI.
keywords: >-
personal access token, PAT, Docker Hub, docker login,
CLI authentication, token permissions, token expiration,
two-factor authentication, SSO
weight: 10
aliases:
- /docker-hub/access-tokens/
- /security/personal-access-tokens/
- /security/for-developers/access-tokens/
- /docker-hub/access-tokens/
- /security/personal-access-tokens/
- /security/for-developers/access-tokens/
---
{{< summary-bar feature_name="PATs" >}}
Personal access tokens (PATs) provide a secure alternative to passwords for Docker CLI authentication. Use PATs to authenticate automated systems, CI/CD pipelines, and development tools without exposing your Docker Hub password.
A personal access token (PAT) lets you sign in to Docker Hub without
your password. Use a token for the Docker CLI, scripts, continuous
integration (CI) jobs, and other tools that should act as your account.
## Key benefits
Each token has one permission level. You can create several tokens and
revoke one without changing your password. The token list shows when
each token was last used.
PATs offer significant security advantages over password authentication:
When two-factor authentication is turned on, or single sign-on is
enforced, password sign-in to the CLI isn't supported. Sign in with a
PAT instead.
- Enhanced security: Investigate token usage, disable suspicious tokens, and prevent administrative actions that could compromise your account if your system is compromised.
- Better automation: Issue multiple tokens for different integrations, each with specific permissions, and revoke them independently when no longer needed.
- Two-factor authentication compatibility: Required when you have two-factor authentication turned on, providing secure CLI access without bypassing 2FA protection.
- Usage tracking: Monitor when and how tokens are used to identify potential security issues or unused automation.
## Who should use personal access tokens?
Use PATs for these common scenarios:
- Development workflows: Authenticate Docker CLI during local development
- CI/CD pipelines: Automate image builds and deployments in continuous integration systems
- Automation scripts: Push and pull images in automated deployment or backup scripts
- Development tools: Integrate Docker Hub access with IDEs, container management tools, or monitoring systems
- Two-factor authentication: Required for CLI access when 2FA is turned on
> [!NOTE]
> [!TIP]
>
> For organization-wide automation, consider [organization access tokens](/manuals/security/access-tokens/organization-access-tokens.md) which aren't tied to individual user accounts.
> For organization-wide automation, consider
> [organization access tokens (OATs)](/manuals/security/access-tokens/organization-access-tokens.md),
> which aren't tied to individual user accounts.
## Create a personal access token
> [!IMPORTANT]
>
> Treat access tokens like passwords and keep them secure. Store tokens in credential managers and never commit them to source code repositories.
To create a personal access token:
Treat PATs like passwords and keep them secure. Store tokens in a
credential manager and never commit them to source code. Before you create a PAT, you must verify your email address. To create a PAT:
1. Sign in to [Docker Home](https://app.docker.com/).
1. Select your avatar in the top-right corner and from the drop-down menu select **Account settings**.
1. Select your avatar in the top-right corner, then select
**Account settings**.
1. Select **Personal access tokens**.
1. Select **Generate new token**.
1. Configure your token:
- **Description:** Use a descriptive name that indicates the token's purpose
- **Expiration date:** Set an expiration date based on your security policies
- **Access permissions:** **Read**, **Write**, or **Delete**.
1. Select **Generate**. 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.
- **Access token description:** Enter a name for the token, up to
100 characters. This field is required.
- **Expiration date:** Optional. Select **30 days**, **90 days**, or
**Custom**. With **Custom**, choose a date and hour up to one year
from today. The default, **None**, creates a token that doesn't
expire.
- **Access permissions:** Select one
[permission level](/manuals/security/access-tokens/reference.md#personal-access-token-permissions).
The default is **Repo Public Read-only**.
1. Select **Generate**. Copy the token and save it. Docker shows the
token once and doesn't store it. You can't retrieve it after you
leave the page.
## Use personal access tokens
## Sign in
Sign in to the Docker CLI using your personal access token:
Run `docker login` with your Docker ID. When the CLI asks for a
password, paste the PAT.
```console
$ docker login --username <YOUR_USERNAME>
Password: [paste your PAT here]
```
When prompted for a password, enter your personal access token instead of your Docker Hub password.
If sign-in fails with `Incorrect authentication credentials`, see
[Why does sign-in fail with "Incorrect authentication credentials"?](/manuals/faqs/accounts.md#why-does-sign-in-fail-with-incorrect-authentication-credentials).
## Modify personal access tokens
## Update or delete
> [!NOTE]
>
> You can't edit the expiration date on an existing personal access token. You must create a new PAT if you need to set a new expiration date.
You can rename a token, change its permissions, deactivate it, activate
it again, or delete it. You can't edit the expiration date on an
existing PAT. Create a new token if you need a different expiration
date.
You can rename, activate, deactivate, or delete a token as needed. You can manage your tokens in your account settings.
1. Sign in to [Docker Home](https://app.docker.com/login).
1. Select your avatar in the top-right corner and from the drop-down menu select **Account settings**.
1. Sign in to [Docker Home](https://app.docker.com/).
1. Select your avatar in the top-right corner, then select
**Account settings**.
1. Select **Personal access tokens**.
- This page shows an overview of all your tokens, and lists if the token was generated manually or if it was
[auto-generated](#auto-generated-tokens). You can also view the scope of the
tokens, which tokens are activate and inactive, when they were created, when
they were last used, and their expiration date.
1. Select the actions menu on the far right of a token row, then select **Deactivate** or **Activate**, **Edit**, or **Delete** to modify the token.
1. After editing the token, select **Save token**.
The list shows each token's description, scope, and status
(**Active**, **Inactive**, or **Revoked**). It also shows whether
the token is **Manual** or
[**Auto-generated**](#auto-generated-tokens), when it was created,
when it was last used, and when it expires.
1. Select the actions menu on the far right of a token row, then select
**Deactivate**, **Activate**, **Edit**, or **Delete**.
A deactivated token stops working until you activate it again.
Expired and revoked tokens can only be deleted.
1. If you selected **Edit**, change the **Access token description** or
**Scopes**, then select **Save token**.
## Auto-generated tokens
Docker Desktop automatically creates authentication tokens when you sign in, with these characteristics:
Signing in to Docker Desktop creates a PAT for CLI
authentication. These tokens show **Auto-generated** in the **Source**
column. A token with no description is listed as "Generated by Docker
Desktop for CLI usage".
- Automatic creation: Generated when you sign in to Docker Desktop
- Full permissions: Include Read, Write, and Delete access
- Session-based: Automatically removed when Docker Desktop session expires
- Account limits: Up to 5 auto-generated tokens per account
- Automatic cleanup: Older tokens are deleted when new ones are created
You can have up to five auto-generated tokens on your account. When
Docker Desktop creates another one, the least recently used
auto-generated token is deleted. A token that has never been used is
ranked by when it was created. Tokens you create yourself are not
deleted.
You can manually delete auto-generated tokens if needed, but they'll be recreated when you use Docker Desktop.
You can deactivate or delete an auto-generated token the same way as
any other token.
## Fair use policy
When using personal access tokens, be aware that excessive token creation may result in throttling or additional charges. Docker reserves the right to impose restrictions on accounts with excessive PAT usage to ensure fair resource allocation and maintain service quality.
When using PATs, be aware that excessive token
creation may result in throttling or additional charges. Docker
reserves the right to impose restrictions on accounts with excessive
PAT usage to ensure fair resource allocation and maintain service
quality.
Best practices for fair use include:
- Reuse tokens across similar use cases instead of creating many single-purpose tokens
- Reuse tokens across similar use cases instead of creating many
single-purpose tokens
- Delete unused tokens regularly
- Use [organization access tokens](/manuals/security/access-tokens/organization-access-tokens.md) for organization-wide automation
- Use [OATs](/manuals/security/access-tokens/organization-access-tokens.md)
for organization-wide automation
- Monitor token usage to identify optimization opportunities
## Next steps
- [Choose a PAT or OAT](/manuals/security/access-tokens/_index.md)
- [Look up PAT permissions](/manuals/security/access-tokens/reference.md#personal-access-token-permissions)
- [Create an OAT](/manuals/security/access-tokens/organization-access-tokens.md)
- [Turn on two-factor authentication](/manuals/security/authentication/2fa/_index.md)

View File

@@ -0,0 +1,189 @@
---
title: Access token reference
linkTitle: Reference
description: >-
Personal access token permissions, organization access token scopes,
and the Docker Hub API endpoints an organization access token can call.
keywords: >-
access token reference, personal access token permissions,
organization access token scopes, Docker Hub API, OAT, PAT
weight: 30
---
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](/manuals/security/access-tokens/personal-access-tokens.md#create-a-personal-access-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](/manuals/ai/sandboxes-api/authentication.md).
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](/manuals/security/access-tokens/organization-access-tokens.md#create-an-organization-access-token)
or
[edit](/manuals/security/access-tokens/organization-access-tokens.md#update-deactivate-or-delete)
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**.
| Scope | Value | Grants |
| --- | --- | --- |
| Image Pull | `scope-image-pull` | Pull images |
| Image Push | `scope-image-push` | Push images. Includes Image Pull |
| Image Delete | `scope-image-delete` | Delete images and tags through registry endpoints. Includes Image Push |
| Repository Read | `scope-repository-read` | Read repository metadata, the Dockerfile, and stars |
| Repository Edit | `scope-repository-edit` | Edit privacy, categories, Dockerfile, description, and stars. Includes Repository Read |
| Repository Admin | `scope-repository-admin` | Delete the repository. Includes Repository Edit |
| Tag Read | `scope-tag-read` | List and read tags, image lists, attestations, and compose files |
| Tag Admin | `scope-tag-admin` | Delete tags. Includes Tag Read |
| Webhook Read | `scope-webhook-read` | List webhook pipelines and delivery history |
| Webhook Edit | `scope-webhook-edit` | Create webhook pipelines. Includes Webhook Read |
| Webhook Admin | `scope-webhook-admin` | Delete webhook pipelines. Includes Webhook Edit |
| Repository Group Read | `scope-repo-group-read` | List and read repository group assignments |
| Repository Group Edit | `scope-repo-group-edit` | Create and update repository group assignments. Includes Repository Group Read |
| Repository Group Admin | `scope-repo-group-admin` | Delete repository group assignments. Includes Repository Group Edit |
| Repository Settings Admin | `scope-repository-settings-admin` | Configure immutable tag rules |
### Organization scopes
Organization scopes apply to the whole organization.
| Scope | Value | Grants |
| --- | --- | --- |
| Member Read | `scope-member-read` | Read organization members |
| Member Edit | `scope-member-edit` | Edit organization members. Includes Member Read |
| Invite Read | `scope-invite-read` | Read invitations |
| Invite Edit | `scope-invite-edit` | Edit invitations. Includes Invite Read |
| Group Read | `scope-group-read` | Read the organization's groups (teams) |
| Group Edit | `scope-group-edit` | Edit the organization's groups (teams). Includes Group Read |
| Audit Log Read | `scope-activity-read` | Read the organization's activity logs |
| SIEM Credentials Read | `scope-siem_credentials-read` | Read SIEM destination settings, including credentials |
| Registry Access Management Read | `scope-ram-read` | Read Registry Access Management settings |
| Registry Access Management Edit | `scope-ram-write` | Edit Registry Access Management settings. Includes Registry Access Management Read |
| Report Read | `scope-report-read` | Download organization usage reports |
| Repository Create | `scope-repository-create` | Create repositories in the organization namespace |
| Repository List | `scope-repository-list` | List all repositories in the namespace, including private ones |
| Registry Usage Read | `scope-registry-usage-read` | Read namespace-level registry usage metrics |
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.
| Section | Scope | Value | Grants |
| --- | --- | --- | --- |
| Docker Build Cloud | Cloud Connect | `scope-cloud-connect` | Connect to, build with, and run on Docker Build Cloud |
| Docker Governance | Audit Events Read | `scope-audit_events-read` | Read governance audit events |
| Docker Governance | Governance Policy Read | `scope-governance-policy-read` | Read governance policies |
| Docker Governance | Governance Policy Write | `scope-governance-policy-write` | Write governance policies. Includes Governance Policy Read |
## Docker Hub API
An OAT can authenticate most Docker Hub API endpoints under
`/v2/namespaces/{namespace}/repositories/`. First
[create an OAT](/manuals/security/access-tokens/organization-access-tokens.md#create-an-organization-access-token),
then exchange it for a short-lived bearer token with the
[Create access token](/reference/api/hub/latest/operations/AuthCreateAccessToken/)
API. Use your organization name as the identifier and the OAT as the
secret:
```console
$ 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:
```console
$ 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](/reference/api/hub/latest/operations/GetRepository/)
- `GET /v2/repositories/{namespace}`: use
[List repositories](/reference/api/hub/latest/operations/listNamespaceRepositories/)
- `GET /v2/users/{username}/repositories`: use
[List repositories](/reference/api/hub/latest/operations/listNamespaceRepositories/)
## Next steps
- [Create a PAT](/manuals/security/access-tokens/personal-access-tokens.md#create-a-personal-access-token)
- [Create an OAT](/manuals/security/access-tokens/organization-access-tokens.md#create-an-organization-access-token)
- [Choose a PAT or OAT](/manuals/security/access-tokens/_index.md)

View File

@@ -305,7 +305,12 @@ which centralizes authentication and enforces policies set by the IdP.
Before enforcing SSO, users accessing Docker through the CLI must
[create a personal access token (PAT)](/manuals/security/access-tokens/personal-access-tokens.md).
The PAT replaces their username and password for authentication.
The PAT replaces their password for authentication. For CI/CD and other
automation, replace passwords with a PAT or an
[organization access token (OAT)](/manuals/security/access-tokens/organization-access-tokens.md).
For GitHub Actions, you can use an
[OIDC connection](/manuals/security/authentication/oidc-connections/_index.md)
instead of storing a long-lived token.
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization or company.
@@ -323,6 +328,7 @@ you want to use 2FA, you must enable 2FA through your IdP.
- [Provision users](/manuals/security/provisioning/_index.md).
- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md).
- [Create personal access tokens](/manuals/security/access-tokens/personal-access-tokens.md).
- [Choose a PAT or OAT](/manuals/security/access-tokens/_index.md).
- [Set up OIDC connections for GitHub Actions](/manuals/security/authentication/oidc-connections/_index.md).
- [Troubleshoot SSO](/manuals/security/authentication/single-sign-on/troubleshoot-sso.md)
issues.