Added documentation for docker.io OAuth & Accounts

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)

docs/sources/reference/api/README.md

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

docs/sources/reference/api/docker_io_accounts_api.rst

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

docs/sources/reference/api/docker_io_oauth_api.rst

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

docs/sources/reference/api/index.rst

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