docs(oat): document Hub API endpoint OAT support for repos-new

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,71 @@ 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
+`/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.

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.
+
+        <span class="oat"></span>
       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.
+
+        <span class="oat"></span>
       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.
+
+        <span class="oat"></span>
       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.
+
+        <span class="oat"></span>
       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.**
+
+        <span class="oat"></span>
       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.**
+
+        <span class="oat"></span>
       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.
+
+        <span class="oat"></span>
       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.
+
+        <span class="oat"></span>
+
+        **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.
+
+        <span class="oat"></span>
       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.
+
+        <span class="oat"></span>
       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.
+
+        <span class="oat"></span>
       tags:
         - repositories
       security: