The following resources are available to interact with the documented API:

• Docker Hub CLI tool (currently experimental)

The Docker Hub API is limited on the amount of requests you can perform per minute against it.

If you haven't hit the limit, each request to the API will return the following headers in the response.

• X-RateLimit-Limit - The limit of requests per minute.
• X-RateLimit-Remaining - The remaining amount of calls within the limit period.
• X-RateLimit-Reset - The unix timestamp of when the remaining resets.

If you have hit the limit, you will receive a response status of 429 and the Retry-After header in the response.

The Retry-After header specifies the number of seconds to wait until you can call the API again.

Note: These rate limits are separate from anti-abuse and Docker Hub download, or pull rate limiting. To learn more about Docker Hub pull rate limiting, see Usage and limits.

Most Docker Hub API endpoints require you to authenticate using your Docker credentials before using them.

Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your subscription (Personal, Pro, or Team) and your account's permissions.

To learn more about the features available in each subscription and to upgrade your existing subscription, see Docker Pricing.

Types

The Docker Hub API supports the following authentication types.

You must use each authentication type with the Create access token route to obtain a bearer token.

Password

Using a username and password is the most powerful, yet least secure way to authenticate with Docker as a user. It allows access to resources for the user without scopes.

In general, it is recommended to use a personal access token (PAT) instead.

The password authentication type is not available if your organization has SSO enforced.

Personal Access Token (PAT)

Using a username and PAT is the most secure way to authenticate with Docker as a user. PATs are scoped to specific resources and scopes.

Currently, a PAT is a more secure password due to limited functionality. In the future, we may add fine-grained access like organization access tokens for enhanced usage and security.

Organization Access Token (OAT)

Organization access tokens are scoped to specific resources and scopes in an organization. They are managed by organization owners.

These tokens are meant for automation and are not meant to be used by users.

Operations that support bearer tokens issued from OATs state this in their descriptions.

The authentication endpoints allow you to authenticate with Docker Hub APIs.

For more information, see Authentication.

The Personal Access Token endpoints lets you manage personal access tokens. For more information, see Access Tokens.

You can use a personal access token instead of a password in the Docker CLI or in the Create an authentication token route to obtain a bearer token.

Scopes

For each scope grouping (in this case "repo"), you only need to define 1 scope as any lower scopes are assumed. For example: If you define repo:write, the API assumes the scope of both repo:read and repo:public_read as well. If you were to define both repo:write and repo:read, then repo:read is assumed by repo:write and ignored.

Treat your personal access token like your password and keep it secret. You cannot retrieve your token after it is generated.

The Audit Logs API endpoints allow you to query audit log events across a namespace.

For more information, see Audit Logs.

The organization endpoints allow you to interact with and manage your organizations.

For more information, see Organization administration overview.

The groups endpoints allow you to manage your organization's teams and their members.

For more information, see Create and manage a team.

The invites endpoints allow you to manage invites for users to join your Docker organization.

For more information, see Invite members.

SCIM is a provisioning system that lets you manage users within your identity provider (IdP).

For more information, see System for Cross-domain Identity management.

The organization access token endpoints allow you to manage organization access tokens (OATs). See Organization access tokens for more information.

OATs only authenticate requests to the modern namespace-scoped routes under /v2/namespaces/{namespace}/repositories/. Legacy repository paths are OAT unsupported, regardless of the token's scopes, and reject every OAT with 403 token issued from organization access token is not allowed:

• GET /v2/repositories/{namespace}/{repository} — use Get repository instead.
• GET /v2/repositories/{namespace} — use List repositories instead.
• GET /v2/users/{username}/repositories — use List repositories instead.