diff --git a/content/reference/api/hub/latest.md b/content/reference/api/hub/latest.md index a9cd8fceff..df2007f591 100644 --- a/content/reference/api/hub/latest.md +++ b/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 --- diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index 86d2f3b30d..b7bcc27129 100644 --- a/content/reference/api/hub/latest.yaml +++ b/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 PAT instead of a password if your organization has SSO enforced.**_ + _**As of September 16, 2024, this route requires a personal access token (PAT) instead of a password if your organization has SSO enforced.**_ + +
+ Deprecated: Use [Create access token] instead. +
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: