Introduction

You can read how the various API's function before accessing and using them further in this section. They are grouped by account management, search, and reindex.

Use the Accounts and Repositories API to integrate Docker Trusted Registry with your enterprise's organizational structure by providing fine-grained, role-based access control for your Docker container images. Specifically, this section describes:

An API for account management

• creating user and organization accounts
• viewing existing accounts
• creating a team within an organization
• viewing teams in an organization
• managing team membership
• editing user and team LDAP syncing configurations

An API for Docker container image repository management and access control

• creating a repository
• viewing repositories owned by an account
• managing user access to a user-owned repository
• managing team access to an organization-owned repository
• managing team access to an organization-owned repository namespace

Overview

This API defines two types of accounts: Users and Organizations. Each account consists of a namespace of repositories with two component names: account-name/repository-name.

Repositories are either public or private.

Public:

• visible to all accounts in the system
• can only be written to by accounts granted explicit write access

Private:

• cannot be discovered by any account unless having explicit read access to it
• can be created by both types of accounts

User Accounts

Docker Trusted Registry users can create repositories under their own namespace as well as share access to their repositories with other users. They can grant read-only, read-write, or admin access to individual users on a per-repository basis.

The following permissions are granted to the individual users with the corresponding access level on the user-owned repository:

Note: Only the owning user account can create and delete repositories from their namespace.

User owned repositories can only be accessed by the owner and other individual user accounts. For example, access to a user-owned repository cannot be granted to a team of users in an organization. If a repository requires this level of access control, consider moving it within an organization namespace.

Organization accounts

System administrators can also create an organization account, with its own namespace of repositories. Organization accounts are comprised of one or more teams which can be managed by anyone in an initial "owners" team. That is created by default. Organization owners have the highest level of permission within the organization, with the ability to manage all teams and repositories.

To be an organization member, a user must be a member of one or more teams within the organization. Only an organization owner can create, modify, or delete teams. However, teams and team membership are visible to all members of the organization. Organization members and teams are not visible to users outside the organization.

Teams

Teams are configured in two ways:

• As a list of users managed by an organization owner, or
• Through LDAP system integration which can then be periodically synced

Teams within an organization may be granted read-only, read-write, or admin level access to the organization's namespace of repositories. This grants certain permissions to members of a team for all repositories belonging to the organization. It allows a team to create, pull, push, or manage repository access for all repositories within an organization but not manage the teams themselves.

The following table depicts what type of access is granted to team members with the corresponding permissions:

In addition to these namespace-wide repository access controls, teams within an organization may also be granted read-only, read-write, or admin level access to individual repositories owned by the organization. The following permissions are granted to the members of teams with the corresponding access level on the organization-owned repository:

Each team can be given a combination of entire-namespace access and more granular per-repository access. However, these permissions are strictly additive, meaning you cannot override a team level permission to prevent access to a specific repository. For example, if a team has read-write access to the entire namespace of repositories, granting that team 'read-only' access to a specific repository will not reduce their access to that repository as the team will still have read-write access to that repository through its namespace access.

Organization-owned repositories can only be given access to the teams within that organization. For example, you cannot grant access to an organization-owned repository to an individual user account or team in another organization. If this level of control is needed on a repository, you can add those individual users to a team within the owning organization. Or you can add users in the other organization's team to a team within the owning organization.

Note: When using the Docker Trusted Registry user interface to assign users global read-only, read-write, or admin roles, they will have that access level to all repositories in the system. You can access and modify these roles with the API, using the _global organization. However, you must have admin access in order to view and edit the _global organization.

Notable differences from Docker Hub

• Repositories must be explicitly created using the API. A docker push will not create a repository if it does not exist. This prevents a typo from creating an unwanted repository in Docker Trusted Registry. This policy will be globally enforced in the Docker Trusted Registry 1.4.

• Only system admins can create organizations. This should prevent the proliferation of unwanted organization accounts.

• Collaborators on user-owned repositories can be given more granular access than on Docker Hub. Docker Hub Registry offers only read-write access. Docker Trusted Registry offers read-only, read-write, and admin access for each user-owned repository.

• Teams can be granted access to all repositories in an organization's namespace. Docker Hub Registry offers team access control on a per-repository level only, and only an organization's "owners" team can manage access and create new repositories.

• Teams and membership within an organization are visible to all members of the organization. In Docker Hub Registry, teams are hidden from users which they are not a member of. In Docker Trusted Registry, teams are visible to all members of the organization.

Authentication

Clients authenticate API requests by providing Basic Authentication credentials (username and password) via an "Authorization" header for each request.

$ curl --user readuser:password https://dtr.example.com/api/v0/accounts
{
  "accounts": [
    {
      "id": 1,
      "type": "user",
      "name": "admin",
    },
    {
      "id": 2,
      "type": "user",
      "name": "readuser",
    }
  ]
}

Note: If you are using Docker Trusted Registry's automatically generated, self-signed SSL certificate then you'll need to add --insecure to the curl examples.

Errors

Errors are always returned as a list and have the following structure:

{
    "errors": [
        {
            "code": "NO_SUCH_TEAM",
            "detail": "Team name: \"team1\".",
            "message": "A team with the given name does not exist in the organization."
        }
    ]
}