docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #22002 from technicallyjosh/main 

Add new auth token docs
This commit is contained in:
Josh 2025-02-12 12:38:30 -07:00 committed by GitHub
parent e6d34217e8 64dfe010e1
commit dc2456054f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 135 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
content/reference/api/hub/latest.md
View File

@ -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
---

139
content/reference/api/hub/latest.yaml
View File

@ -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.**_
<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: