Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.serval.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The DockerHub Organization integration covers the operations the sibling DockerHub integration cannot. Personal Access Tokens (PATs) are deliberately scoped by Docker Hub to repository operations only — calls to org/team/group endpoints return 403 token issued from personal access token is not allowed. To automate org membership, teams, and repository permissions you need an Organization Access Token (OAT).

Key Features

  • Look up org members and search by email
  • Create, update, and delete teams (groups)
  • Add and remove members from teams
  • Grant and revoke a team’s access to a repository

Common Use Cases

  • Provision/deprovision Docker Hub access during onboarding/offboarding
  • Self-service requests that grant a user write access to a specific repo
  • Quarterly access reviews — list members and their team memberships
  • Bulk apply repo-permission policies across an organization

​
When to use this vs the DockerHub (PAT) integration

NeedIntegration
Audit a repository, list tags, delete tags, update descriptionDockerHub (PAT)
List or search organization membersDockerHub Organization (OAT)
Create teams, add members to teamsDockerHub Organization (OAT)
Grant or revoke a team’s access to a repositoryDockerHub Organization (OAT)
Workflows that need both can configure them side-by-side and union the contexts. The two integrations do not depend on each other.

​
Prerequisites

1

Docker Hub organization

An active Docker Hub organization that you administer.
2

Organization Access Token (OAT)

OATs are issued through Docker’s first-party enrollment flows — they are not the same as Personal Access Tokens, and there is no public third-party OAuth app registration to mint them. Typical sources:
  • docker org connect from a workstation logged in with an org admin
  • The Docker Hub partner OAuth pilot (gated by Docker)
  • Docker Desktop’s “Connect organization” flow
3

Organization name

The exact org slug as it appears in URLs and API paths (/v2/orgs/{org_name}/).
If you don’t have an OAT and only have a Personal Access Token, this integration is not the right one — use the DockerHub integration instead. The PAT will be rejected on every endpoint this integration targets.

​
Setup Instructions

​
Step 1: Obtain an Organization Access Token

OAT issuance is gated by Docker; the most common path today is the Docker CLI’s org-connect flow. If you already use that flow to enroll Docker Desktop or CI runners against your org, that’s the credential to use here. Otherwise, contact your Docker Hub partner contact.

​
Step 2: Configure the integration in Serval

  1. Navigate to the Integrations page in Serval.
  2. Find DockerHub Organization and click Configure.
  3. Enter your configuration details.
​
organizationName
string
required
The Docker Hub organization slug — the {org_name} segment in URLs like hub.docker.com/u/{org_name} or API paths like /v2/orgs/{org_name}/.
​
organizationAccessToken
string
required
The Organization Access Token from Step 1. Serval stores this encrypted and never exposes it to workflow code. Behind the scenes, the proxy exchanges the OAT for a short-lived JWT at POST hub.docker.com/v2/auth/token (with {identifier: organizationName, secret: oat} per Docker Hub’s spec) and uses the resulting JWT as the Bearer header. The JWT is cached and refreshed automatically; workflow code never sees either secret.
​
instanceName
string
required
A friendly label to distinguish this connection from others (for example, Production, Sandbox Org). Required when you have multiple DockerHub Organization connections on the same team.
  1. Click Submit to establish the integration.
Integration configured. Serval will run three healthchecks: verifying the OAT, listing one org member, and listing one team.

​
API surface

All paths match Docker Hub’s public OpenAPI spec exactly. Trailing slashes matter — none of these paths take one, and Docker Hub returns 404 if you add one.
  • GET /v2/orgs/{org_name}/members — list and search (search, page, page_size, invites, role)
  • PUT /v2/orgs/{org_name}/members/{username} — update role {role: "owner" | "editor" | "member"}
  • DELETE /v2/orgs/{org_name}/members/{username} — remove member from org
  • GET /v2/orgs/{org_name}/groups — list teams
  • POST /v2/orgs/{org_name}/groups — create a team {name, description}
  • GET /v2/orgs/{org_name}/groups/{group_name} — team details
  • PATCH /v2/orgs/{org_name}/groups/{group_name} — update name or description
  • DELETE /v2/orgs/{org_name}/groups/{group_name} — delete team
  • GET /v2/orgs/{org_name}/groups/{group_name}/members — list members
  • POST /v2/orgs/{org_name}/groups/{group_name}/members — add {member: "username"}
  • DELETE /v2/orgs/{org_name}/groups/{group_name}/members/{username} — remove member
  • GET /v2/orgs/{org_name}/invites — list pending invites
Repository team-grant operations live on the DockerHub (PAT) integration, not here. Docker Hub keeps POST /v2/repositories/{namespace}/{repository}/groups PAT-callable despite the team semantics. The typical “grant team write access to a repo” workflow uses both integrations:
  1. Use this integration to resolve the team’s numeric id via GET /v2/orgs/{org_name}/groups/{group_name}.
  2. Use the PAT integration to call the grant endpoint with { group_id, permission: "write" }.

​
Best Practices

Use a dedicated automation OAT. If your Docker Hub org allows it, enroll a specific service-account principal for Serval rather than reusing an OAT tied to an individual admin.
Team and member operations are durable. Removing a member from a team revokes their repository access immediately. Wrap any DELETE workflow in an approval procedure.
The user must already be an org member. Adding a username to a team with POST .../members does not auto-invite them — DockerHub returns an error. Use a separate workflow step to confirm membership first.

​
Additional Resources

Docker Hub API reference

Complete reference for the Hub REST API.

Docker Hub security & tokens

Background on PATs and OATs.
Need help? Contact support@serval.com for assistance with your DockerHub Organization integration.