Merge pull request #22002 from technicallyjosh/main

Add new auth token docs

content/reference/api/hub/latest.md

@@ -1,6 +1,6 @@
 ---
 layout: api
-description: Reference documentation and Swagger (OpenAPI) specification for the Docker Hub API.
+description: Reference documentation and OpenAPI specification for the Docker Hub API.
 title: Docker Hub API reference
 linkTitle: Docker Hub API
 ---

content/reference/api/hub/latest.yaml

@@ -1,4 +1,6 @@
-openapi: 3.0.0
+# yaml-language-server: $schema=https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/main/schemas/v3.0/schema.yaml
+
+openapi: 3.0.3
 info:
   title: Docker HUB API
   version: beta
@@ -111,14 +113,18 @@ paths:
         - authentication
       summary: Create an authentication token
       operationId: PostUsersLogin
+      security: []
+      deprecated: true
       description: |
         Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.
 
         The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.
 
-        Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.
+        _**As of September 16, 2024, this route requires a personal access token (PAT) instead of a password if your organization has SSO enforced.**_
-
+        
-        _**As of September 16, 2024, this route requires a PAT instead of a password if your organization has SSO enforced.**_
+        <div style="background-color:rgb(255, 165, 0, .25); padding:5px; border-radius:4px">
+          <strong>Deprecated</strong>: Use [<a href="#tag/authentication/operation/AuthCreateAccessToken">Create access token</a>] instead.
+        </div>
       requestBody:
         content:
           application/json:
@@ -145,6 +151,7 @@ paths:
         - authentication
       summary: Second factor authentication
       operationId: PostUsers2FALogin
+      security: []
       description: |
         When a user has two-factor authentication (2FA) enabled, this is the second call to perform after `/v2/users/login` call.
 
@@ -168,17 +175,65 @@ paths:
               schema:
                 $ref: '#/components/schemas/PostUsersLoginSuccessResponse'
         '401':
-          description: Authentication failed or second factor required
+          description: Authentication failed
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/PostUsers2FALoginErrorResponse'
+  /v2/auth/token:
+    post:
+      tags:
+        - authentication
+      security: []
+      summary: Create access token
+      operationId: AuthCreateAccessToken
+      description: |
+        Creates and returns a short-lived access token in JWT format for use as a bearer when calling Docker APIs.
+        
+        If successful, the access token returned should be used in the HTTP Authorization header like 
+        `Authorization: Bearer {access_token}`.
+
+        _**If your organization has SSO enforced, you must use a personal access token (PAT) instead of a password.**_
+      requestBody:
+        content:
+          application/json:
+            schema:
+              description: Request to create access token
+              type: object
+              required:
+                - identifier
+                - secret
+              properties:
+                identifier:
+                  description: |
+                    The identifier of the account to create an access token for. If using a password or personal access token,
+                    this must be a username. If using an organization access token, this must be an organization name.
+                  type: string
+                  example: myusername
+                secret:
+                  description: |
+                    The secret of the account to create an access token for. This can be a password, personal access token, or
+                    organization access token.
+                  type: string
+                  example: dckr_pat_124509ugsdjga93
+      responses:
+        '200':
+          description: Token created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AuthCreateTokenResponse'
+        '401':
+          description: Authentication failed
+          $ref: '#/components/responses/unauthorized'
   /v2/access-tokens:
     post:
       summary: Create a personal access token
       description: Creates and returns a personal access token.
       tags:
         - access-tokens
+      security:
+        - bearerAuth: []
       requestBody:
         content:
           application/json:
@@ -201,6 +256,8 @@ paths:
       description: Returns a paginated list of personal access tokens.
       tags:
         - access-tokens
+      security: 
+        - bearerAuth: []
       parameters:
         - in: query
           name: page
@@ -236,6 +293,8 @@ paths:
         Updates a personal access token partially. You can either update the token's label or enable/disable it.
       tags:
         - access-tokens
+      security: 
+        - bearerAuth: []
       requestBody:
         content:
           application/json:
@@ -258,6 +317,8 @@ paths:
       description: Returns a personal access token by UUID.
       tags:
         - access-tokens
+      security: 
+        - bearerAuth: []
       responses:
         '200':
           description: OK
@@ -281,6 +342,8 @@ paths:
         Deletes a personal access token permanently. This cannot be undone.
       tags:
         - access-tokens
+      security: 
+        - bearerAuth: []
       responses:
         '204':
           description: A successful response.
@@ -293,6 +356,8 @@ paths:
       summary: Returns list of audit log events
       description: Get audit log events for a given namespace.
       operationId: AuditLogs_GetAuditLogs
+      security:
+        - bearerAuth: []
       responses:
         '200':
           description: A successful response.
@@ -401,6 +466,8 @@ paths:
       description: |
         Get audit log actions for a namespace to be used as a filter for querying audit events.
       operationId: AuditLogs_GetAuditActions
+      security: 
+        - bearerAuth: []
       responses:
         '200':
           description: A successful response.
@@ -498,6 +565,8 @@ paths:
         Returns organization settings by name.
       tags:
         - org-settings
+      security: 
+        - bearerAuth: []
       responses:
         '200':
           description: OK
@@ -522,6 +591,8 @@ paths:
         - `restricted_images`
       tags:
         - org-settings
+      security: 
+        - bearerAuth: []
       requestBody:
         content:
           application/json:
@@ -559,6 +630,8 @@ paths:
       summary: List repository tags
       tags:
         - repositories
+      security: 
+        - bearerAuth: []
       parameters:
         - in: query
           name: page
@@ -583,6 +656,8 @@ paths:
       summary: Check repository tags
       tags:
         - repositories
+      security: 
+        - bearerAuth: []
       responses:
         '200':
           description: Repository contains tags
@@ -599,6 +674,8 @@ paths:
       summary: Read repository tag
       tags:
         - repositories
+      security: 
+        - bearerAuth: []
       responses:
         '200':
           $ref: '#/components/responses/get_tag'
@@ -610,6 +687,8 @@ paths:
       summary: Check repository tag
       tags:
         - repositories
+      security: 
+        - bearerAuth: []
       responses:
         '200':
           description: Repository tag exists
@@ -633,6 +712,8 @@ paths:
         Returns a list of members for an organization"
       tags:
         - orgs
+      security: 
+        - bearerAuth: []
       responses:
         '200':
           description: List of members
@@ -660,6 +741,8 @@ paths:
         Export members of an organization as a CSV
       tags:
         - orgs
+      security: 
+        - bearerAuth: []
       responses:
         '200':
           description: Exported members
@@ -731,6 +814,8 @@ paths:
         ***Only users in the "owners" group of the organization can use this endpoint.***
       tags:
         - orgs
+      security: 
+        - bearerAuth: []
       requestBody:
         required: true
         content:
@@ -767,6 +852,8 @@ paths:
         Removes the member from the org, ie. all groups in the org, unless they're the last owner
       tags:
         - orgs
+      security: 
+        - bearerAuth: []
       responses:
         '204':
           description: Member removed successfully
@@ -788,6 +875,8 @@ paths:
         Return all pending invites for a given org, only team owners can call this endpoint
       tags:
         - invites
+      security: 
+        - bearerAuth: []
       responses:
         '200':
           description: ''
@@ -814,6 +903,8 @@ paths:
       summary: Get groups of an organization
       tags:
         - groups
+      security: 
+        - bearerAuth: []
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/page_size'
@@ -858,6 +949,8 @@ paths:
       description: Create a new group within an organization.
       tags:
         - groups
+      security: 
+        - bearerAuth: []
       requestBody:
         content:
           application/json:
@@ -891,6 +984,8 @@ paths:
       summary: Get a group of an organization
       tags:
         - groups
+      security: 
+        - bearerAuth: []
       responses:
         '200':
           description: ''
@@ -908,6 +1003,8 @@ paths:
       summary: Update the details for an organization group
       tags:
         - groups
+      security: 
+        - bearerAuth: []
       requestBody:
         content:
           application/json:
@@ -936,6 +1033,8 @@ paths:
       summary: Update some details for an organization group
       tags:
         - groups
+      security: 
+        - bearerAuth: []
       requestBody:
         content:
           application/json:
@@ -962,6 +1061,8 @@ paths:
       summary: Delete an organization group
       tags:
         - groups
+      security: 
+        - bearerAuth: []
       responses:
         '204':
           description: Group deleted successfully
@@ -974,6 +1075,8 @@ paths:
   /v2/orgs/{org_name}/groups/{group_name}/members:
     x-audience: public
     get:
+      security: 
+        - bearerAuth: []
       parameters:
         - $ref: '#/components/parameters/org_name'
         - $ref: '#/components/parameters/group_name'
@@ -1023,6 +1126,8 @@ paths:
       summary: Adds a member to a group
       tags:
         - groups
+      security: 
+        - bearerAuth: []
       requestBody:
         $ref: '#/components/requestBodies/add_member_to_org_group'
       responses:
@@ -1046,6 +1151,8 @@ paths:
       summary: Removes a user from a group
       tags:
         - groups
+      security: 
+        - bearerAuth: []
       responses:
         '204':
           description: User removed successfully
@@ -1069,6 +1176,8 @@ paths:
         Mark the invite as cancelled so it doesn't show up on the list of pending invites
       tags:
         - invites
+      security: 
+        - bearerAuth: []
       responses:
         '204':
           description: ''
@@ -1092,6 +1201,8 @@ paths:
         Resend a pending invite to the user, any org owner can resend an invite
       tags:
         - invites
+      security: 
+        - bearerAuth: []
       responses:
         '204':
           description: ''
@@ -1113,6 +1224,8 @@ paths:
         - invites
       requestBody:
         $ref: '#/components/requestBodies/bulk_invite_request'
+      security: 
+        - bearerAuth: []
       responses:
         '202':
           description: Accepted
@@ -1639,6 +1752,14 @@ components:
             The password or personal access token (PAT) of the Docker Hub account to authenticate with.
           type: string
           example: p@ssw0rd
+    AuthCreateTokenResponse:
+      description: successful access token response
+      type: object
+      properties:
+        access_token:
+          description: The created access token. This expires in 10 minutes.
+          type: string
+          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
     PostUsersLoginSuccessResponse:
       description: successful user login response
       type: object
@@ -2744,6 +2865,14 @@ components:
               member:
                 type: string
                 example: jonsnow
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+    bearerSCIMAuth:
+      type: http
+      scheme: bearer
 x-tagGroups:
   - name: General
     tags: