Skip to main content
Authenticate with a container registry via Personal Access Token.

Parameters

ParameterTypeDefaultDescription
registry_urlstringrequiredRegistry URL (e.g., docker://ghcr.io/org/image)
usernamestringrequiredRegistry username
tokenstringrequiredPersonal Access Token

URL Parsing

InputRegistry
docker://ghcr.io/org/imageghcr.io
oci://registry.gitlab.com/org/imageregistry.gitlab.com
alpine or library/alpinedocker.io (implicit)

Examples

Docker Hub:
{"registry_url": "docker://docker.io/library/alpine", "username": "myuser", "token": "dckr_pat_xxx"}
GitHub Container Registry:
{"registry_url": "docker://ghcr.io/org/image", "username": "myuser", "token": "ghp_xxx"}

Response

Success:
{
  "status": "success",
  "registry": "docker.io",
  "message": "Authenticated with 'docker.io' as 'myuser' successfully."
}
Invalid credentials:
{
  "status": "error",
  "registry": "docker.io",
  "message": "Invalid credentials for 'docker.io'. Please verify your username and PAT."
}

Token Storage

  • Credentials are validated via OCI /v2/ API before storage
  • Stored in local cache and persisted across sessions
  • Tokens are revalidated before each import_image call
  • Expired tokens are automatically removed from cache

Workflow

  1. Call registry_token_obtain → opens browser
  2. User creates read-only PAT in registry web UI
  3. User provides username and token
  4. Call registry_auth → validates and stores credentials
  5. Call import_image to import images