diff --git a/docs/sources/reference/api/README.md b/docs/sources/reference/api/README.md index 10dede382b..ec42b89733 100644 --- a/docs/sources/reference/api/README.md +++ b/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 diff --git a/docs/sources/reference/api/_static/io_oauth_authorization_page.jpg b/docs/sources/reference/api/_static/io_oauth_authorization_page.jpg new file mode 100644 index 0000000000..5c331987c2 Binary files /dev/null and b/docs/sources/reference/api/_static/io_oauth_authorization_page.jpg differ diff --git a/docs/sources/reference/api/docker_io_accounts_api.rst b/docs/sources/reference/api/docker_io_accounts_api.rst new file mode 100644 index 0000000000..7976f1fddf --- /dev/null +++ b/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 diff --git a/docs/sources/reference/api/docker_io_oauth_api.rst b/docs/sources/reference/api/docker_io_oauth_api.rst new file mode 100644 index 0000000000..bed939f7d1 --- /dev/null +++ b/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 `_. + + +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 diff --git a/docs/sources/reference/api/index.rst b/docs/sources/reference/api/index.rst index 017369143c..3c84a505c6 100644 --- a/docs/sources/reference/api/index.rst +++ b/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