From 161f7610059253e97c221f49d0e0fc3af0537512 Mon Sep 17 00:00:00 2001 From: Vincent DAMERY Date: Fri, 14 Aug 2026 17:17:50 +0200 Subject: [PATCH 1/3] docs(hub-api): add OAT markers to repository endpoints Adds labels to all repository-related endpoints that accept org access tokens via the AllowOAT() middleware: - GET/POST /v2/namespaces/{namespace}/repositories - GET/HEAD /v2/namespaces/{namespace}/repositories/{repository} - GET/HEAD /v2/namespaces/{namespace}/repositories/{repository}/tags - GET/HEAD /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag} - PATCH/POST /v2/namespaces/{namespace}/repositories/{repository}/immutabletags - POST /v2/repositories/{namespace}/{repository}/groups Also documents the OAT-specific listing behavior on GET repositories: an OAT with scope-repository-list sees all repos including private; without it, only public repos are returned. Co-Authored-By: Claude Sonnet 4.6 --- content/reference/api/hub/latest.yaml | 38 +++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index 38034331654a..a7466d2efd88 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -1039,6 +1039,10 @@ paths: get: operationId: ListRepositoryTags summary: List repository tags + description: | + Returns the list of tags for the specified repository. + + tags: - repositories security: @@ -1065,6 +1069,10 @@ paths: $ref: "#/components/responses/NotFound" head: summary: Check repository tags + description: | + Checks whether the repository has any tags. + + tags: - repositories security: @@ -1084,6 +1092,10 @@ paths: get: operationId: GetRepositoryTag summary: Read repository tag + description: | + Returns details for a specific tag in the specified repository. + + tags: - repositories security: @@ -1097,6 +1109,10 @@ paths: $ref: "#/components/responses/NotFound" head: summary: Check repository tag + description: | + Checks whether the specified tag exists in the repository. + + tags: - repositories security: @@ -1119,6 +1135,8 @@ paths: Updates the immutable tags configuration for this repository. **Only users with administrative privileges for the repository can modify these settings.** + + tags: - repositories security: @@ -1144,9 +1162,11 @@ paths: operationId: VerifyRepositoryImmutableTags summary: "Verify repository immutable tags" description: | - Validates the immutable tags regex pass in parameter and returns a list of tags matching it in this repository. + Validates the immutable tags regex passed in the request body and returns a list of tags matching it in this repository. - **Only users with administrative privileges for the repository call this endpoint.** + **Only users with administrative privileges for the repository can call this endpoint.** + + tags: - repositories security: @@ -1170,6 +1190,10 @@ paths: - $ref: "#/components/parameters/repository" post: summary: Assign a group (Team) to a repository for access + description: | + Assigns an organization group (team) to a repository with a specified permission level. + + tags: - repositories operationId: CreateRepositoryGroup @@ -1217,6 +1241,10 @@ paths: Returns a list of repositories within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. + + + + **OAT listing behavior**: an OAT with the `scope-repository-list` scope sees all repositories including private ones. An OAT without that scope only sees public repositories. tags: - repositories security: @@ -1360,6 +1388,8 @@ paths: description: | Creates a new repository within the specified namespace. The repository will be created with the provided metadata including name, description, and privacy settings. + + operationId: CreateRepository tags: - repositories @@ -1431,6 +1461,8 @@ paths: Returns a repository within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. + + tags: - repositories security: @@ -1482,6 +1514,8 @@ paths: Check a repository within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. + + tags: - repositories security: From 4d4abfd4ebd94b48c8307d6913a8029794ca615b Mon Sep 17 00:00:00 2001 From: Vincent DAMERY Date: Fri, 14 Aug 2026 17:28:00 +0200 Subject: [PATCH 2/3] docs(oat): document Hub API endpoint support for org access tokens MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a Hub API support section to the OAT manual page explaining: - Which endpoint categories accept OAT authentication - The scope-based listing behavior on GET /v2/namespaces/{ns}/repositories (scope-repository-list → all repos including private; else public-only) - Endpoints that do not support OAT (manifests, collaborators, settings) Co-Authored-By: Claude Sonnet 4.6 --- .../enterprise/security/access-tokens.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/content/manuals/enterprise/security/access-tokens.md b/content/manuals/enterprise/security/access-tokens.md index f7432821dac5..889c7406bc82 100644 --- a/content/manuals/enterprise/security/access-tokens.md +++ b/content/manuals/enterprise/security/access-tokens.md @@ -104,6 +104,35 @@ organization. - **Delete** 1. Select **Save** after making changes to a token. +## 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. + + ## Organization access token best practices - Regular token rotation: Set reasonable expiration dates and rotate tokens regularly to minimize security risks. From 4302f749b016bb0914381f9e7e3ef24765a373c7 Mon Sep 17 00:00:00 2001 From: Vincent DAMERY Date: Fri, 14 Aug 2026 18:06:24 +0200 Subject: [PATCH 3/3] docs: add OAT scopes reference table and update token creation steps Add a new "Available scopes" section documenting all repository-level and organization-level OAT scopes with their descriptions and scope hierarchy (which higher scopes include lower ones). Update the "Create an organization access token" section to reference the full scope list and include the new org-level scopes (scope-repository-list, scope-repository-create, scope-registry-usage-read) in the organization permissions step. --- .../enterprise/security/access-tokens.md | 48 +++++++++++++++++-- 1 file changed, 45 insertions(+), 3 deletions(-) diff --git a/content/manuals/enterprise/security/access-tokens.md b/content/manuals/enterprise/security/access-tokens.md index 889c7406bc82..9013dc21feeb 100644 --- a/content/manuals/enterprise/security/access-tokens.md +++ b/content/manuals/enterprise/security/access-tokens.md @@ -62,18 +62,24 @@ organization. - 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 access permissions: +1. Expand the **Repository** drop-down to set per-repository access permissions: 1. Optional. Select **Read public repositories** for access to public repositories. 1. Select **Add repository** and choose a repository from the drop-down. - 1. Set permissions for each repository: **Image Pull** or **Image Push**. + 1. 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. 1. Add up to 50 repositories as needed. -1. Optional. Configure organization management permissions by expanding the **Organization** drop-down and selecting the **Allow management access to this organization's resources**: +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. > [!IMPORTANT] @@ -104,6 +110,42 @@ organization. - **Delete** 1. 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 + +| 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 | — | + +### Organization scopes + +| 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 | + ## Hub API support OATs can authenticate requests to most Docker Hub API endpoints under