Docker Hub Authentication API

openapi: 3.2.0
info:
  title: Docker HUB Authentication API
  version: 2-beta
  x-logo:
    url: https://docs.docker.com/assets/images/logo-docker-main.png
    href: /reference
  description: 'Docker Hub is a service provided by Docker for finding and sharing container images with your team.


    It is the world''s largest library and community for container images.


    In addition to the Docker Hub UI and Docker Hub CLI tool (currently experimental), Docker provides an API that allows you to interact with Docker Hub.


    Browse through the Docker Hub API documentation to explore the supported endpoints.'
servers:
- description: Docker HUB API
  x-audience: public
  url: https://hub.docker.com
tags:
- name: Authentication API
  x-displayName: Authentication
  description: 'The authentication endpoints allow you to authenticate with Docker Hub APIs.


    For more information, see Authentication.'
paths:
  /v2/users/login:
    post:
      tags:
      - Authentication API
      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}`.


        _**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:
            schema:
              $ref: '#/components/schemas/UsersLoginRequest'
        description: Login details.
        required: true
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostUsersLoginSuccessResponse'
        '401':
          description: Authentication failed or second factor required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostUsersLoginErrorResponse'
  /v2/users/2fa-login:
    post:
      tags:
      - Authentication API
      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.


        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.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Users2FALoginRequest'
        description: Login details.
        required: true
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostUsersLoginSuccessResponse'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostUsers2FALoginErrorResponse'
  /v2/auth/token:
    post:
      tags:
      - Authentication API
      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'
components:
  schemas:
    PostUsersLoginSuccessResponse:
      description: successful user login response
      type: object
      properties:
        token:
          description: 'Created authentication token.

            This token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs.

            '
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
    PostUsers2FALoginErrorResponse:
      description: failed second factor login response.
      type: object
      properties:
        detail:
          description: Description of the error.
          type: string
          example: Incorrect authentication credentials
    UsersLoginRequest:
      description: User login details
      type: object
      required:
      - username
      - password
      properties:
        username:
          description: The username of the Docker Hub account to authenticate with.
          type: string
          example: myusername
        password:
          description: 'The password or personal access token (PAT) of the Docker Hub account to authenticate with.

            '
          type: string
          example: p@ssw0rd
    error:
      type: object
      properties:
        errinfo:
          type: object
          items:
            type: string
        detail:
          type: string
        message:
          type: string
    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
    Users2FALoginRequest:
      description: Second factor user login details
      type: object
      required:
      - login_2fa_token
      - code
      properties:
        login_2fa_token:
          description: The intermediate 2FA token returned from `/v2/users/login` API.
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        code:
          description: 'The Time-based One-Time Password of the Docker Hub account to authenticate with.

            '
          type: string
          example: 123456
    PostUsersLoginErrorResponse:
      description: failed user login response or second factor required
      type: object
      required:
      - detail
      properties:
        detail:
          description: Description of the error.
          type: string
          example: Incorrect authentication credentials
        login_2fa_token:
          description: 'Short time lived token to be used on `/v2/users/2fa-login` to complete the authentication. This field is present only if 2FA is enabled.

            '
          type:
          - string
          - 'null'
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
  responses:
    unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    bearerSCIMAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: General
  tags:
  - changelog
  - resources
  - rate-limiting
  - authentication
- name: API
  tags:
  - authentication-api
  - access-tokens
  - images
  - audit-logs
  - org-settings
  - repositories
  - scim
  - orgs
  - org-access-tokens
  - groups
  - invites