1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
page_title: docker.io OAuth API
page_description: API Documentation for docker.io's OAuth flow.
page_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](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](mailto:support-accounts%40docker.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.
`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 Parameters:
- **client_id** – The `client_id` given to
your application at registration.
- **response_type** – MUST be set to `code`.
This specifies that you would like an Authorization Code
returned.
- **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.
- **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.
- **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.
`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.
Request Headers:
- **Authorization** – HTTP basic authentication using your
application's `client_id` and
`client_secret`
Form Parameters:
- **grant_type** – MUST be set to `authorization_code`
- **code** – The authorization code received from the user's
redirect request.
- **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.
`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.
Request Headers:
- **Authorization** – HTTP basic authentication using your
application's `client_id` and
`client_secret`
Form Parameters:
- **grant_type** – MUST be set to `refresh_token`
- **refresh_token** – The `refresh_token`
which was issued to your application.
- **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
|
