mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
00bb76f35b
OAuth docs: documented the OAuth authorization flow and how to register your application Account docs: documented getting/updating user profile data documented getting/updating user email data Docker-DCO-1.1-Signed-off-by: Josh hawn <josh.hawn@docker.com> (github: jlhawn)
308 lines
9.6 KiB
ReStructuredText
308 lines
9.6 KiB
ReStructuredText
:title: docker.io Accounts API
|
|
:description: API Documentation for docker.io accounts.
|
|
:keywords: API, Docker, accounts, REST, documentation
|
|
|
|
|
|
======================
|
|
docker.io Accounts API
|
|
======================
|
|
|
|
.. contents:: Table of Contents
|
|
|
|
|
|
1. Endpoints
|
|
============
|
|
|
|
|
|
1.1 Get a single user
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. http:get:: /api/v1.1/users/:username/
|
|
|
|
Get profile info for the specified user.
|
|
|
|
:param username: username of the user whose profile info is being requested.
|
|
|
|
:reqheader Authorization: required authentication credentials of either type HTTP Basic or OAuth Bearer Token.
|
|
|
|
:statuscode 200: success, user data returned.
|
|
:statuscode 401: authentication error.
|
|
:statuscode 403: permission error, authenticated user must be the user whose data is being requested, OAuth access tokens must have ``profile_read`` scope.
|
|
:statuscode 404: the specified username does not exist.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1.1/users/janedoe/ HTTP/1.1
|
|
Host: www.docker.io
|
|
Accept: application/json
|
|
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"id": 2,
|
|
"username": "janedoe",
|
|
"url": "",
|
|
"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_email": "jane.doe+gravatar@example.com",
|
|
"email": "jane.doe@example.com",
|
|
"is_active": true
|
|
}
|
|
|
|
|
|
1.2 Update a single user
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. http:patch:: /api/v1.1/users/:username/
|
|
|
|
Update profile info for the specified user.
|
|
|
|
:param username: username of the user whose profile info is being updated.
|
|
|
|
:jsonparam string full_name: (optional) the new name of the user.
|
|
:jsonparam string location: (optional) the new location.
|
|
:jsonparam string company: (optional) the new company of the user.
|
|
:jsonparam string profile_url: (optional) the new profile url.
|
|
:jsonparam string gravatar_email: (optional) the new Gravatar email address.
|
|
|
|
:reqheader Authorization: required authentication credentials of either type HTTP Basic or OAuth Bearer Token.
|
|
:reqheader Content-Type: MIME Type of post data. JSON, url-encoded form data, etc.
|
|
|
|
:statuscode 200: success, user data updated.
|
|
:statuscode 400: post data validation error.
|
|
:statuscode 401: authentication error.
|
|
:statuscode 403: permission error, authenticated user must be the user whose data is being updated, OAuth access tokens must have ``profile_write`` scope.
|
|
:statuscode 404: the specified username does not exist.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
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**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"id": 2,
|
|
"username": "janedoe",
|
|
"url": "",
|
|
"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_email": "jane.doe+gravatar@example.com",
|
|
"email": "jane.doe@example.com",
|
|
"is_active": true
|
|
}
|
|
|
|
|
|
1.3 List email addresses for a user
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. http:get:: /api/v1.1/users/:username/emails/
|
|
|
|
List email info for the specified user.
|
|
|
|
:param username: username of the user whose profile info is being updated.
|
|
|
|
:reqheader Authorization: required authentication credentials of either type HTTP Basic or OAuth Bearer Token
|
|
|
|
:statuscode 200: success, user data updated.
|
|
:statuscode 401: authentication error.
|
|
:statuscode 403: permission error, authenticated user must be the user whose data is being requested, OAuth access tokens must have ``email_read`` scope.
|
|
:statuscode 404: the specified username does not exist.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1.1/users/janedoe/emails/ HTTP/1.1
|
|
Host: www.docker.io
|
|
Accept: application/json
|
|
Authorization: Bearer zAy0BxC1wDv2EuF3tGs4HrI6qJp6KoL7nM
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
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
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. http: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.
|
|
|
|
:jsonparam string email: email address to be added.
|
|
|
|
:reqheader Authorization: required authentication credentials of either type HTTP Basic or OAuth Bearer Token.
|
|
:reqheader Content-Type: MIME Type of post data. JSON, url-encoded form data, etc.
|
|
|
|
:statuscode 201: success, new email added.
|
|
:statuscode 400: data validation error.
|
|
:statuscode 401: authentication error.
|
|
:statuscode 403: permission error, authenticated user must be the user whose data is being requested, OAuth access tokens must have ``email_write`` scope.
|
|
:statuscode 404: the specified username does not exist.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
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**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
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
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. http: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.
|
|
|
|
:param username: username of the user whose email info is being updated.
|
|
|
|
:jsonparam string email: the email address to be updated.
|
|
:jsonparam boolean verified: (optional) whether the email address is verified, must be ``true`` or absent.
|
|
:jsonparam boolean primary: (optional) whether to set the email address as the primary email, must be ``true`` or absent.
|
|
|
|
:reqheader Authorization: required authentication credentials of either type HTTP Basic or OAuth Bearer Token.
|
|
:reqheader Content-Type: MIME Type of post data. JSON, url-encoded form data, etc.
|
|
|
|
:statuscode 200: success, user's email updated.
|
|
:statuscode 400: data validation error.
|
|
:statuscode 401: authentication error.
|
|
:statuscode 403: permission error, authenticated user must be the user whose data is being updated, OAuth access tokens must have ``email_write`` scope.
|
|
:statuscode 404: the specified username or email address does not exist.
|
|
|
|
**Example request**:
|
|
|
|
Once you have independently verified an email address.
|
|
|
|
.. sourcecode:: http
|
|
|
|
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**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
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
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. http: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.
|
|
|
|
:jsonparam string email: email address to be deleted.
|
|
|
|
:reqheader Authorization: required authentication credentials of either type HTTP Basic or OAuth Bearer Token.
|
|
:reqheader Content-Type: MIME Type of post data. JSON, url-encoded form data, etc.
|
|
|
|
:statuscode 204: success, email address removed.
|
|
:statuscode 400: validation error.
|
|
:statuscode 401: authentication error.
|
|
:statuscode 403: permission error, authenticated user must be the user whose data is being requested, OAuth access tokens must have ``email_write`` scope.
|
|
:statuscode 404: the specified username or email address does not exist.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
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**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 204 NO CONTENT
|
|
Content-Length: 0
|