page_title: docker.io Accounts API
page_description: API Documentation for docker.io accounts.
page_keywords: API, Docker, accounts, REST, documentation

# docker.io Accounts API

## 1. Endpoints

### 1.1 Get a single user

 `GET /api/v1.1/users/:username/`
:   Get profile info for the specified user.

    Parameters:

    -   **username** – username of the user whose profile info is being
        requested.

    Request Headers:

     

    -   **Authorization** – required authentication credentials of
        either type HTTP Basic or OAuth Bearer Token.

    Status Codes:

    -   **200** – success, user data returned.
    -   **401** – authentication error.
    -   **403** – permission error, authenticated user must be the user
        whose data is being requested, OAuth access tokens must have
        `profile_read` scope.
    -   **404** – the specified username does not exist.

    **Example request**:

        GET /api/v1.1/users/janedoe/ HTTP/1.1
        Host: www.docker.io
        Accept: application/json
        Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

    **Example response**:

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "id": 2,
            "username": "janedoe",
            "url": "https://www.docker.io/api/v1.1/users/janedoe/",
            "date_joined": "2014-02-12T17:58:01.431312Z",
            "type": "User",
            "full_name": "Jane Doe",
            "location": "San Francisco, CA",
            "company": "Success, Inc.",
            "profile_url": "https://docker.io/",
            "gravatar_url": "https://secure.gravatar.com/avatar/0212b397124be4acd4e7dea9aa357.jpg?s=80&r=g&d=mm"
            "email": "jane.doe@example.com",
            "is_active": true
        }

### 1.2 Update a single user

 `PATCH /api/v1.1/users/:username/`
:   Update profile info for the specified user.

    Parameters:

    -   **username** – username of the user whose profile info is being
        updated.

    Json Parameters:

     

    -   **full\_name** (*string*) – (optional) the new name of the user.
    -   **location** (*string*) – (optional) the new location.
    -   **company** (*string*) – (optional) the new company of the user.
    -   **profile\_url** (*string*) – (optional) the new profile url.
    -   **gravatar\_email** (*string*) – (optional) the new Gravatar
        email address.

    Request Headers:

     

    -   **Authorization** – required authentication credentials of
        either type HTTP Basic or OAuth Bearer Token.
    -   **Content-Type** – MIME Type of post data. JSON, url-encoded
        form data, etc.

    Status Codes:

    -   **200** – success, user data updated.
    -   **400** – post data validation error.
    -   **401** – authentication error.
    -   **403** – permission error, authenticated user must be the user
        whose data is being updated, OAuth access tokens must have
        `profile_write` scope.
    -   **404** – the specified username does not exist.

    **Example request**:

        PATCH /api/v1.1/users/janedoe/ HTTP/1.1
        Host: www.docker.io
        Accept: application/json
        Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

        {
            "location": "Private Island",
            "profile_url": "http://janedoe.com/",
            "company": "Retired",
        }

    **Example response**:

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "id": 2,
            "username": "janedoe",
            "url": "https://www.docker.io/api/v1.1/users/janedoe/",
            "date_joined": "2014-02-12T17:58:01.431312Z",
            "type": "User",
            "full_name": "Jane Doe",
            "location": "Private Island",
            "company": "Retired",
            "profile_url": "http://janedoe.com/",
            "gravatar_url": "https://secure.gravatar.com/avatar/0212b397124be4acd4e7dea9aa357.jpg?s=80&r=g&d=mm"
            "email": "jane.doe@example.com",
            "is_active": true
        }

### 1.3 List email addresses for a user

 `GET /api/v1.1/users/:username/emails/`
:   List email info for the specified user.

    Parameters:

    -   **username** – username of the user whose profile info is being
        updated.

    Request Headers:

     

    -   **Authorization** – required authentication credentials of
        either type HTTP Basic or OAuth Bearer Token

    Status Codes:

    -   **200** – success, user data updated.
    -   **401** – authentication error.
    -   **403** – permission error, authenticated user must be the user
        whose data is being requested, OAuth access tokens must have
        `email_read` scope.
    -   **404** – the specified username does not exist.

    **Example request**:

        GET /api/v1.1/users/janedoe/emails/ HTTP/1.1
        Host: www.docker.io
        Accept: application/json
        Authorization: Bearer zAy0BxC1wDv2EuF3tGs4HrI6qJp6KoL7nM

    **Example response**:

        HTTP/1.1 200 OK
        Content-Type: application/json

        [
            {
                "email": "jane.doe@example.com",
                "verified": true,
                "primary": true
            }
        ]

### 1.4 Add email address for a user

 `POST /api/v1.1/users/:username/emails/`
:   Add a new email address to the specified user’s account. The email
    address must be verified separately, a confirmation email is not
    automatically sent.

    Json Parameters:

     

    -   **email** (*string*) – email address to be added.

    Request Headers:

     

    -   **Authorization** – required authentication credentials of
        either type HTTP Basic or OAuth Bearer Token.
    -   **Content-Type** – MIME Type of post data. JSON, url-encoded
        form data, etc.

    Status Codes:

    -   **201** – success, new email added.
    -   **400** – data validation error.
    -   **401** – authentication error.
    -   **403** – permission error, authenticated user must be the user
        whose data is being requested, OAuth access tokens must have
        `email_write` scope.
    -   **404** – the specified username does not exist.

    **Example request**:

        POST /api/v1.1/users/janedoe/emails/ HTTP/1.1
        Host: www.docker.io
        Accept: application/json
        Content-Type: application/json
        Authorization: Bearer zAy0BxC1wDv2EuF3tGs4HrI6qJp6KoL7nM

        {
            "email": "jane.doe+other@example.com"
        }

    **Example response**:

        HTTP/1.1 201 Created
        Content-Type: application/json

        {
            "email": "jane.doe+other@example.com",
            "verified": false,
            "primary": false
        }

### 1.5 Update an email address for a user

 `PATCH /api/v1.1/users/:username/emails/`
:   Update an email address for the specified user to either verify an
    email address or set it as the primary email for the user. You
    cannot use this endpoint to un-verify an email address. You cannot
    use this endpoint to unset the primary email, only set another as
    the primary.

    Parameters:

    -   **username** – username of the user whose email info is being
        updated.

    Json Parameters:

     

    -   **email** (*string*) – the email address to be updated.
    -   **verified** (*boolean*) – (optional) whether the email address
        is verified, must be `true` or absent.
    -   **primary** (*boolean*) – (optional) whether to set the email
        address as the primary email, must be `true`
        or absent.

    Request Headers:

     

    -   **Authorization** – required authentication credentials of
        either type HTTP Basic or OAuth Bearer Token.
    -   **Content-Type** – MIME Type of post data. JSON, url-encoded
        form data, etc.

    Status Codes:

    -   **200** – success, user’s email updated.
    -   **400** – data validation error.
    -   **401** – authentication error.
    -   **403** – permission error, authenticated user must be the user
        whose data is being updated, OAuth access tokens must have
        `email_write` scope.
    -   **404** – the specified username or email address does not
        exist.

    **Example request**:

    Once you have independently verified an email address.

        PATCH /api/v1.1/users/janedoe/emails/ HTTP/1.1
        Host: www.docker.io
        Accept: application/json
        Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

        {
            "email": "jane.doe+other@example.com",
            "verified": true,
        }

    **Example response**:

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "email": "jane.doe+other@example.com",
            "verified": true,
            "primary": false
        }

### 1.6 Delete email address for a user

 `DELETE /api/v1.1/users/:username/emails/`
:   Delete an email address from the specified user’s account. You
    cannot delete a user’s primary email address.

    Json Parameters:

     

    -   **email** (*string*) – email address to be deleted.

    Request Headers:

     

    -   **Authorization** – required authentication credentials of
        either type HTTP Basic or OAuth Bearer Token.
    -   **Content-Type** – MIME Type of post data. JSON, url-encoded
        form data, etc.

    Status Codes:

    -   **204** – success, email address removed.
    -   **400** – validation error.
    -   **401** – authentication error.
    -   **403** – permission error, authenticated user must be the user
        whose data is being requested, OAuth access tokens must have
        `email_write` scope.
    -   **404** – the specified username or email address does not
        exist.

    **Example request**:

        DELETE /api/v1.1/users/janedoe/emails/ HTTP/1.1
        Host: www.docker.io
        Accept: application/json
        Content-Type: application/json
        Authorization: Bearer zAy0BxC1wDv2EuF3tGs4HrI6qJp6KoL7nM

        {
            "email": "jane.doe+other@example.com"
        }

    **Example response**:

        HTTP/1.1 204 NO CONTENT
        Content-Length: 0