moby/docs/sources/reference/api/docker_io_accounts_api.md

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