mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
Merge pull request #4319 from jlhawn/docs-docker-io-api
Added documentation for docker.io OAuth & Accounts
This commit is contained in:
Andy Rothfusz
commit
70d2ca4ed3
5 changed files with 564 additions and 0 deletions
|
|
@ -3,3 +3,4 @@ This directory holds the authoritative specifications of APIs defined and implem
|
|||
* The remote API by which a docker node can be queried over HTTP
|
||||
* The registry API by which a docker node can download and upload container images for storage and sharing
|
||||
* The index search API by which a docker node can search the public index for images to download
|
||||
* The docker.io OAuth and accounts API which 3rd party services can use to access account information
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 175 KiB |
308
docs/sources/reference/api/docker_io_accounts_api.rst
Normal file
308
docs/sources/reference/api/docker_io_accounts_api.rst
Normal file
|
|
@ -0,0 +1,308 @@
|
|||
: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
|
||||
253
docs/sources/reference/api/docker_io_oauth_api.rst
Normal file
253
docs/sources/reference/api/docker_io_oauth_api.rst
Normal file
|
|
@ -0,0 +1,253 @@
|
|||
:title: docker.io OAuth API
|
||||
:description: API Documentation for docker.io's OAuth flow.
|
||||
:keywords: API, Docker, oauth, REST, documentation
|
||||
|
||||
|
||||
===================
|
||||
docker.io OAuth API
|
||||
===================
|
||||
|
||||
.. contents:: Table of Contents
|
||||
|
||||
|
||||
1. Brief introduction
|
||||
=====================
|
||||
|
||||
Some docker.io API requests will require an access token to authenticate. To
|
||||
get an access token for a user, that user must first grant your application
|
||||
access to their docker.io account. In order for them to grant your application
|
||||
access you must first register your application.
|
||||
|
||||
Before continuing, we encourage you to familiarize yourself with
|
||||
`The OAuth 2.0 Authorization Framework <http://tools.ietf.org/html/rfc6749>`_.
|
||||
|
||||
*Also note that all OAuth interactions must take place over https connections*
|
||||
|
||||
|
||||
2. Register Your Application
|
||||
============================
|
||||
|
||||
You will need to register your application with docker.io before users will
|
||||
be able to grant your application access to their account information. We
|
||||
are currently only allowing applications selectively. To request registration
|
||||
of your application send an email to support-accounts@docker.com with the
|
||||
following information:
|
||||
|
||||
- The name of your application
|
||||
- A description of your application and the service it will provide
|
||||
to docker.io users.
|
||||
- A callback URI that we will use for redirecting authorization requests to
|
||||
your application. These are used in the step of getting an Authorization
|
||||
Code. The domain name of the callback URI will be visible to the user when
|
||||
they are requested to authorize your application.
|
||||
|
||||
When your application is approved you will receive a response from the
|
||||
docker.io team with your ``client_id`` and ``client_secret`` which your
|
||||
application will use in the steps of getting an Authorization Code and getting
|
||||
an Access Token.
|
||||
|
||||
|
||||
3. Endpoints
|
||||
============
|
||||
|
||||
3.1 Get an Authorization Code
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Once You have registered you are ready to start integrating docker.io accounts
|
||||
into your application! The process is usually started by a user following a
|
||||
link in your application to an OAuth Authorization endpoint.
|
||||
|
||||
.. http:get:: /api/v1.1/o/authorize/
|
||||
|
||||
Request that a docker.io user authorize your application. If the user is
|
||||
not already logged in, they will be prompted to login. The user is then
|
||||
presented with a form to authorize your application for the requested
|
||||
access scope. On submission, the user will be redirected to the specified
|
||||
``redirect_uri`` with an Authorization Code.
|
||||
|
||||
:query client_id: The ``client_id`` given to your application at
|
||||
registration.
|
||||
:query response_type: MUST be set to ``code``. This specifies that you
|
||||
would like an Authorization Code returned.
|
||||
:query redirect_uri: The URI to redirect back to after the user has
|
||||
authorized your application. If omitted, the first of your registered
|
||||
``response_uris`` is used. If included, it must be one of the URIs
|
||||
which were submitted when registering your application.
|
||||
:query scope: The extent of access permissions you are requesting.
|
||||
Currently, the scope options are ``profile_read``, ``profile_write``,
|
||||
``email_read``, and ``email_write``. Scopes must be separated by a
|
||||
space. If omitted, the default scopes ``profile_read email_read`` are
|
||||
used.
|
||||
:query state: (Recommended) Used by your application to maintain state
|
||||
between the authorization request and callback to protect against CSRF
|
||||
attacks.
|
||||
|
||||
**Example Request**
|
||||
|
||||
Asking the user for authorization.
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /api/v1.1/o/authorize/?client_id=TestClientID&response_type=code&redirect_uri=https%3A//my.app/auth_complete/&scope=profile_read%20email_read&state=abc123 HTTP/1.1
|
||||
Host: www.docker.io
|
||||
|
||||
**Authorization Page**
|
||||
|
||||
When the user follows a link, making the above GET request, they will be
|
||||
asked to login to their docker.io account if they are not already and then
|
||||
be presented with the following authorization prompt which asks the user
|
||||
to authorize your application with a description of the requested scopes.
|
||||
|
||||
.. image:: _static/io_oauth_authorization_page.png
|
||||
|
||||
Once the user allows or denies your Authorization Request the user will be
|
||||
redirected back to your application. Included in that request will be the
|
||||
following query parameters:
|
||||
|
||||
``code``
|
||||
The Authorization code generated by the docker.io authorization server.
|
||||
Present it again to request an Access Token. This code expires in 60
|
||||
seconds.
|
||||
|
||||
``state``
|
||||
If the ``state`` parameter was present in the authorization request this
|
||||
will be the exact value received from that request.
|
||||
|
||||
``error``
|
||||
An error message in the event of the user denying the authorization or
|
||||
some other kind of error with the request.
|
||||
|
||||
|
||||
3.2 Get an Access Token
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Once the user has authorized your application, a request will be made to your
|
||||
application's specified ``redirect_uri`` which includes a ``code`` parameter
|
||||
that you must then use to get an Access Token.
|
||||
|
||||
.. http:post:: /api/v1.1/o/token/
|
||||
|
||||
Submit your newly granted Authorization Code and your application's
|
||||
credentials to receive an Access Token and Refresh Token. The code is valid
|
||||
for 60 seconds and cannot be used more than once.
|
||||
|
||||
:reqheader Authorization: HTTP basic authentication using your
|
||||
application's ``client_id`` and ``client_secret``
|
||||
|
||||
:form grant_type: MUST be set to ``authorization_code``
|
||||
:form code: The authorization code received from the user's redirect
|
||||
request.
|
||||
:form redirect_uri: The same ``redirect_uri`` used in the authentication
|
||||
request.
|
||||
|
||||
**Example Request**
|
||||
|
||||
Using an authorization code to get an access token.
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
POST /api/v1.1/o/token/ HTTP/1.1
|
||||
Host: www.docker.io
|
||||
Authorization: Basic VGVzdENsaWVudElEOlRlc3RDbGllbnRTZWNyZXQ=
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"grant_type": "code",
|
||||
"code": "YXV0aG9yaXphdGlvbl9jb2Rl",
|
||||
"redirect_uri": "https://my.app/auth_complete/"
|
||||
}
|
||||
|
||||
**Example Response**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json;charset=UTF-8
|
||||
|
||||
{
|
||||
"username": "janedoe",
|
||||
"user_id": 42,
|
||||
"access_token": "t6k2BqgRw59hphQBsbBoPPWLqu6FmS",
|
||||
"expires_in": 15552000,
|
||||
"token_type": "Bearer",
|
||||
"scope": "profile_read email_read",
|
||||
"refresh_token": "hJDhLH3cfsUrQlT4MxA6s8xAFEqdgc"
|
||||
}
|
||||
|
||||
In the case of an error, there will be a non-200 HTTP Status and and data
|
||||
detailing the error.
|
||||
|
||||
|
||||
3.3 Refresh a Token
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Once the Access Token expires you can use your ``refresh_token`` to have
|
||||
docker.io issue your application a new Access Token, if the user has not
|
||||
revoked access from your application.
|
||||
|
||||
.. http:post:: /api/v1.1/o/token/
|
||||
|
||||
Submit your ``refresh_token`` and application's credentials to receive a
|
||||
new Access Token and Refresh Token. The ``refresh_token`` can be used
|
||||
only once.
|
||||
|
||||
:reqheader Authorization: HTTP basic authentication using your
|
||||
application's ``client_id`` and ``client_secret``
|
||||
|
||||
:form grant_type: MUST be set to ``refresh_token``
|
||||
:form refresh_token: The ``refresh_token`` which was issued to your
|
||||
application.
|
||||
:form scope: (optional) The scope of the access token to be returned.
|
||||
Must not include any scope not originally granted by the user and if
|
||||
omitted is treated as equal to the scope originally granted.
|
||||
|
||||
**Example Request**
|
||||
|
||||
Refreshing an access token.
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
POST /api/v1.1/o/token/ HTTP/1.1
|
||||
Host: www.docker.io
|
||||
Authorization: Basic VGVzdENsaWVudElEOlRlc3RDbGllbnRTZWNyZXQ=
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"grant_type": "refresh_token",
|
||||
"refresh_token": "hJDhLH3cfsUrQlT4MxA6s8xAFEqdgc",
|
||||
}
|
||||
|
||||
**Example Response**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json;charset=UTF-8
|
||||
|
||||
{
|
||||
"username": "janedoe",
|
||||
"user_id": 42,
|
||||
"access_token": "t6k2BqgRw59hphQBsbBoPPWLqu6FmS",
|
||||
"expires_in": 15552000,
|
||||
"token_type": "Bearer",
|
||||
"scope": "profile_read email_read",
|
||||
"refresh_token": "hJDhLH3cfsUrQlT4MxA6s8xAFEqdgc"
|
||||
}
|
||||
|
||||
In the case of an error, there will be a non-200 HTTP Status and and data
|
||||
detailing the error.
|
||||
|
||||
|
||||
4. Use an Access Token with the API
|
||||
===================================
|
||||
|
||||
Many of the docker.io API requests will require a Authorization request header
|
||||
field. Simply ensure you add this header with "Bearer <``access_token``>":
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /api/v1.1/resource HTTP/1.1
|
||||
Host: docker.io
|
||||
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
|
||||
|
|
@ -15,4 +15,6 @@ Your programs and scripts can access Docker's functionality via these interfaces
|
|||
index_api
|
||||
docker_remote_api
|
||||
remote_api_client_libraries
|
||||
docker_io_oauth_api
|
||||
docker_io_accounts_api
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue