Skip to main content

​
About DockerHub Organization

The DockerHub Organization integration connects Serval to a Docker Hub organization using an Organization Access Token (OAT). It covers the organization-administration side of Docker Hub: listing and searching members, changing member roles, removing members, viewing pending invites, and creating and managing teams (Docker Hub calls them groups). Repository-level work - image tags, repository descriptions, and granting teams access to repositories - lives on the sibling DockerHub integration instead. Serval talks to a single host for this integration: hub.docker.com. Authentication: Organization Access Token (OAT). Serval stores the token encrypted and exchanges it behind the scenes for a short-lived session credential when workflows make requests, caching and refreshing that credential automatically - your workflows never see the raw token. Data sync: On-demand only. Nothing is imported or polled in the background; Serval calls Docker Hub at the moment a workflow runs an action.

​
What the DockerHub Organization integration enables

These capabilities map to the organization-management surface of the Docker Hub API. Repository-level endpoints are deliberately left to the sibling DockerHub integration.

​
Get your credentials

You need two things: your organization’s exact name (slug) on Docker Hub, and an Organization Access Token (OAT) issued for that organization. An OAT is an opaque secret starting with dckr_oat_ that carries organization-admin scopes such as Member Read and Group Read. See Docker’s organization access tokens documentation for full details.
An OAT is a different credential class from a Personal Access Token. You cannot create one in Docker Hub under Account Settings > Personal access tokens, and a Personal Access Token will not work with this integration. If you only have a Personal Access Token, use the sibling DockerHub integration for repository operations instead.
1

Check the prerequisites

OATs are created in the Docker Admin Console by an organization owner. Docker requires a Docker Team or Business subscription: Team plans allow up to 10 OATs per organization, Business plans up to 100.
2

Open the Admin Console

Sign in to Docker Home, select your organization, then select Admin Console, then Access tokens.
3

Generate the token

Select Generate access token, then give the token a label, an optional description, and an expiration date. Under the organization permissions, grant the scopes that cover the operations your workflows will use: Member Read and Member Edit for listing members and changing or removing them, Invite Read for pending invites, and Group Read and Group Edit for team management. This integration only uses the organization permissions; repository permissions (Image Pull and Image Push) can be left unset.
4

Note your organization name

Record the exact organization slug - the segment that follows hub.docker.com/u/ in your organization’s Docker Hub page address. You will enter it as the Organization Name in Serval.
Copy the token somewhere safe as soon as it is issued. You will paste it into Serval in the next section.

​
Connect in Serval

1

Open the connect form

In Serval, add a new DockerHub Organization connection.
2

Enter the Organization Name (required)

Type your Docker Hub organization slug into the field with placeholder “your-dockerhub-org”. Extra spaces are trimmed automatically. Leaving it empty fails with: “Organization Name is required.”
3

Paste the Organization Access Token (required)

Paste the dckr_oat_ token into the password field. Leaving it empty when first connecting fails with: “Organization Access Token is required.”
4

Enter an Instance Name (required)

Give the connection a friendly label such as “Production” or “Engineering” so you can tell multiple connections apart. Leaving it empty fails with: “Instance Name is required to distinguish multiple DockerHub Organization connections.”
5

Save

Serval stores the token encrypted. When you revisit the form later, the token is shown obfuscated as bullet characters plus its last 4 characters.
When editing a saved connection, any field you leave blank keeps its previously saved value - including the token, so submitting the form with the obfuscated token still in place does not wipe your credential. To rotate the token, paste the new one over it and save. If an update would leave any field empty, it is rejected with: “Organization Name, Organization Access Token, and Instance Name are required.”

​
Verifying the connection

The integration ships three health checks that run against your real organization: Validate DockerHub OAT Connection - confirms the token authenticates and has organization-admin access by fetching a single member of the configured organization.
  • Success: “Successfully authenticated against DockerHub organization “[name]” ([number] members visible).”
  • Failure: “Unable to authenticate against the DockerHub organization. Verify the Organization Access Token has not been revoked, that the Organization Name matches a DockerHub org the OAT was issued for, and that the OAT has org-admin scope.”
Search DockerHub Organization Members - fetches a small sample of the member list, confirming access to the same listing-and-search endpoint real workflows use when resolving a person by email.
  • Success: “Successfully fetched member listing for “[name]” ([number] members; showing first [number]).”
  • Failure: “Unable to list members of the DockerHub organization. Confirm the Organization Access Token has organization-admin scope.”
List DockerHub Organization Groups - confirms the token can list the organization’s teams.
  • Success: “Successfully listed organization groups ([number] total in “[name]”).”
  • Failure: “Unable to list groups in the DockerHub organization. Confirm the Organization Access Token has organization-admin scope.”
If all three checks are green but a workflow still fails when granting a team access to a repository, that is expected: repository grants live on the sibling DockerHub integration, which uses a Personal Access Token. Look up the team here, then perform the grant there.

​
Gotchas and troubleshooting

Docker Hub rejects Personal Access Tokens on every organization, member, and team operation this integration uses, with the message “token issued from personal access token is not allowed”. If you only have a Personal Access Token, use the sibling DockerHub integration for repository operations. This integration requires an Organization Access Token.
The Organization Name does double duty: Serval uses it both to address your organization and to exchange the token for a session credential. A wrong or misspelled Organization Name breaks that exchange even when the token itself is fine. Verify the name exactly matches the organization the token was issued for - it is the slug from your organization’s Docker Hub page address.
Docker Hub will not auto-invite someone who is not already in the organization. Resolve the person first with the member search (for example by email) and confirm they are an organization member before adding them to a team. For workflow builders: the add-to-team operation expects the person’s username in a field named “member”, not “username”.
Docker Hub intentionally keeps repository team-grants callable with a Personal Access Token, so that capability lives on the sibling DockerHub integration. The two-step flow: look up the team here to get its numeric team id, then perform the grant on the DockerHub integration using that id and the desired permission level. A single workflow can use both connections together.
If you build your own requests with the “DockerHub Organization API request” action, do not add a trailing slash to organization paths - Docker Hub returns a not-found error if you do. Docker Hub also has no endpoint that fetches the organization by itself; to verify an organization name and token scope, list one member or one team instead (exactly what the health checks do).
When you edit a saved connection, the stored token is shown obfuscated, and any field left blank - including the token - keeps its previously saved value. Submitting the form without touching the token does not clear the credential. To rotate the token, paste the new one into the Organization Access Token field and save.
List operations return results in pages, with a count and links to the next and previous pages. The default page size is 10 and the maximum is 100, so a workflow that needs every member or team of a large organization should page through the results.
Need help? Contact support@serval.com for assistance with your DockerHub Organization integration.