moby/docs/sources/reference/api/docker_io_oauth_api.rst

title

docker.io OAuth API

description

API Documentation for docker.io's OAuth flow.

keywords

API, Docker, oauth, REST, documentation

docker.io OAuth API

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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>":

GET /api/v1.1/resource HTTP/1.1
Host: docker.io
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA