使用Docker HTTP API V2获取私有镜像Manifest仍遇401错误求助

Let’s break down the common issues that could be causing your 401 error, even after you’ve obtained a Bearer token, and walk through fixes for each:

• Fix the scope parameter in your token request
  The Www-Authenticate header returned uses scope="repository:{username}:pull" as a placeholder — you need to replace this with the full repository path, not just your Docker Hub username. For example, if your private image is myusername/my-private-app, the correct scope should be repository:myusername/my-private-app:pull. Using only your username without the image name will result in a token that doesn’t grant access to the specific repository, leading to a 401.

• Verify your token request includes all required credentials
  When fetching the token from https://auth.docker.io/token, ensure you’re authenticating properly:

  • Use a GET request with query parameters: service=registry.docker.io, scope=repository:<full-repo-path>:pull, plus an Authorization: Basic <base64-encoded-username-password> header (encode your username:password string as Base64 first).
  • Alternatively, send a POST request with grant_type=password, username=<your-username>, and password=<your-password> in the request body.
    Missing or incorrect credentials will generate a token that lacks valid pull permissions.

• Check the Authorization header format
  Make sure your manifest request uses the exact correct header format:

  Authorization: Bearer <your-token>
  

  Common mistakes here include missing the space after Bearer, typos like Bearerr, or extra whitespace around the token. Even small formatting errors will cause the registry to reject the token.

• Confirm the image reference is valid
  Double-check the reference in your /v2/name/manifests/reference request:

  • If using a tag (e.g., latest), verify the tag exists in your private repository.
  • If using a digest (e.g., sha256:abc123...), ensure it matches the exact digest stored in Docker Hub. An incorrect reference will trigger a 401 even with a valid token.

• Validate your repository permissions
  Ensure your Docker Hub account has explicit pull access to the private repository:

  • If the repo belongs to an organization, confirm your user account is added to the organization with the appropriate access level.
  • Check for misconfigured permissions (e.g., if the repo was recently transferred between accounts/organizations, permissions might need to be re-enabled).

• Inspect the token’s content
  Docker Hub’s Bearer tokens are JWTs — you can decode them locally using tools like jq (run echo <your-token> | cut -d '.' -f 2 | base64 -d | jq) to check:

  • The scope claim matches the repository you’re trying to access.
  • The exp (expiration time) is still in the future.
    If either is incorrect, your token won’t work for the request.

内容的提问来源于stack exchange，提问作者Valeri