Skip to main content

Docker Hub

Docker Hub integration allows your product to connect with Docker Hub repositories to fetch container image metadata, list repositories, view tags, and analyze images for security scanning or compliance purposes. This integration is especially useful for DevSecOps workflows, image inventory, and vulnerability management pipelines.

Credentials Needed​

To connect your product with Docker Hub, you need Docker Hub API credentials for authentication.

Required credentials:

  • Docker Hub Username
  • Docker Hub Access Token (or Password)

It is strongly recommended to use a Personal Access Token instead of your Docker Hub account password for security and automation purposes.

Permissions Needed / API Scopes​

Docker Hub uses access tokens with specific scopes. For integrations that only read repository and image data, read-only access is sufficient.

FunctionalityRequired ScopeDescription
Read repositoriesrepository:readAllows listing repositories and fetching metadata
Read image tagsrepository:readAllows reading image tags and manifests
Write (optional)repository:writeAllows pushing or modifying images (not recommended)
Delete (optional)repository:deleteAllows deleting repositories or tags (not recommended)

Recommended Scope: repository:read

Creating Users / Access Tokens​

Step 1: Generate a Personal Access Token

  1. Log in to Docker Hub: https://hub.docker.com/
  2. Click on your profile avatar → Account Settings → Security → Access Tokens.
  3. Click New Access Token.
  4. Provide a name for the token (e.g., DockerHubIntegrationToken).
  5. Under Access permissions, choose:
    • Read-only (recommended for most integrations).
  6. Click Generate.
  7. Copy and securely store the access token — it will only be displayed once.

Test Connectivity​

You can test the credentials using curl or any REST API client:

# Authenticate to Docker Hub
curl -X POST https://hub.docker.com/v2/users/login/ \
    -H "Content-Type: application/json" \
    -d '{"username": "<USERNAME>", "password": "<ACCESS_TOKEN>"}'

# List repositories for the user
curl -H "Authorization: JWT <TOKEN>" https://hub.docker.com/v2/repositories/<USERNAME>/

# List tags in a repository
curl -H "Authorization: JWT <TOKEN>" https://hub.docker.com/v2/repositories/<USERNAME>/<REPO_NAME>/tags/

If you receive valid JSON responses (repository or tag data), your integration credentials and permissions are configured correctly.

Save the Results in the Platform and Create Connection​

  1. In your platform's connector configuration, securely store:
    • DOCKERHUB_USERNAME
    • DOCKERHUB_ACCESS_TOKEN
  2. Create a new connection labeled Docker Hub Integration.
  3. Test the connection by listing repositories or image tags to confirm connectivity.

Best Practices​

  • Use Access Tokens instead of passwords for all integrations.
  • Assign only read-only permissions unless push/write access is required.
  • Store your credentials securely using an encrypted vault or secret manager.
  • Rotate Access Tokens periodically to enhance security.
  • If your platform supports multiple users, allow each to connect with their own Docker Hub token for isolation.
  • Cache repository metadata and tags locally to reduce rate-limit impact from the Docker Hub API.
  • Respect Docker Hub's rate limits — unauthenticated requests are heavily throttled.
  • Use organization-level tokens (if applicable) for enterprise integrations requiring access to multiple team repositories.