@@ -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

new file mode 100644

Binary files /dev/null and b/docs/sources/reference/api/_static/io_oauth_authorization_page.jpg differ

new file mode 100644

@@ -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

new file mode 100644

@@ -0,0 +1,233 @@

+: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>`_.

+

+

+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 list of one or more redirect URIs that we will use for redirecting

+  authorization requests to your application. These are used in the step

+  of getting an Authorization Code.

+

+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=http%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.jpg

+

+    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": "http://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 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