Skip to content

Commit fdfb161

Browse files
technicallyjoshsarahsanders-docker
technicallyjosh
and
sarahsanders-docker
authored
Improve auth docs and add oat tags for use (#22045)
<!--Delete sections as needed --> ## Description This improves our authentication docs in our API. Additionally, we need to note on certain routes where OAT bearers are allowed. ## Related issues or tickets <!-- Related issues, pull requests, or Jira tickets --> ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [x] Technical review - [x] Editorial review - [ ] Product review --------- Co-authored-by: Sarah Sanders <[email protected]>
1 parent 5ba3cdb commit fdfb161

File tree

2 files changed

+115
-9
lines changed

2 files changed

+115
-9
lines changed

‎content/reference/api/hub/latest.yaml‎

Lines changed: 89 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,50 @@ tags:
5050
Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your plan (Personal, Pro, or Team) and your account's permissions.
5151
5252
To learn more about the features available in each plan and to upgrade your existing plan, see [Docker Pricing](https://www.docker.com/pricing).
53+
54+
# Types
55+
56+
The Docker Hub API supports the following authentication types.
57+
58+
You must use each authentication type with the [Create access token](#tag/authentication-api/operation/AuthCreateAccessToken) route to obtain a bearer token.
59+
60+
## Password
61+
Using a username and password is the most powerful, yet least secure way
62+
to authenticate with Docker as a user. It allows access to resources
63+
for the user without scopes.
64+
65+
_In general, it is recommended to use a personal access token (PAT) instead._
66+
67+
_**The password authentication type is not available if your organization has SSO enforced.**_
68+
69+
## Personal Access Token (PAT)
70+
Using a username and PAT is the most secure way to authenticate with
71+
Docker as a user. PATs are scoped to specific resources and scopes.
72+
73+
Currently, a PAT is a more secure password due to limited functionality.
74+
In the future, we may add fine-grained access like organization
75+
access tokens for enhanced usage and security.
76+
77+
## Organization Access Token (OAT)
78+
Organization access tokens are scoped to specific resources and scopes
79+
in an organization. They are managed by organization owners.
80+
81+
These tokens are meant for automation and are not meant to be used by
82+
users.
83+
84+
# Labels
85+
86+
These labels will show up on routes in this reference that allow for use of bearer
87+
tokens issued from them.
88+
89+
<span class="pat"></span>
90+
<span class="oat"></span>
91+
- name: authentication-api
92+
x-displayName: Authentication
93+
description: |
94+
The authentication endpoints allow you to authenticate with Docker Hub APIs.
95+
96+
For more information, see [Authentication](#tag/authentication).
5397
- name: access-tokens
5498
x-displayName: Personal Access Tokens
5599
description: |
@@ -110,7 +154,7 @@ paths:
110154
/v2/users/login:
111155
post:
112156
tags:
113-
- authentication
157+
- authentication-api
114158
summary: Create an authentication token
115159
operationId: PostUsersLogin
116160
security: []
@@ -123,7 +167,7 @@ paths:
123167
_**As of September 16, 2024, this route requires a personal access token (PAT) instead of a password if your organization has SSO enforced.**_
124168
125169
<div style="background-color:rgb(255, 165, 0, .25); padding:5px; border-radius:4px">
126-
<strong>Deprecated</strong>: Use [<a href="#tag/authentication/operation/AuthCreateAccessToken">Create access token</a>] instead.
170+
<strong>Deprecated</strong>: Use [<a href="#tag/authentication-api/operation/AuthCreateAccessToken">Create access token</a>] instead.
127171
</div>
128172
requestBody:
129173
content:
@@ -148,7 +192,7 @@ paths:
148192
/v2/users/2fa-login:
149193
post:
150194
tags:
151-
- authentication
195+
- authentication-api
152196
summary: Second factor authentication
153197
operationId: PostUsers2FALogin
154198
security: []
@@ -183,7 +227,7 @@ paths:
183227
/v2/auth/token:
184228
post:
185229
tags:
186-
- authentication
230+
- authentication-api
187231
security: []
188232
summary: Create access token
189233
operationId: AuthCreateAccessToken
@@ -709,7 +753,9 @@ paths:
709753
get:
710754
summary: List org members
711755
description: |
712-
Returns a list of members for an organization"
756+
Returns a list of members for an organization
757+
758+
<span class="oat"></span>
713759
tags:
714760
- orgs
715761
security:
@@ -739,6 +785,8 @@ paths:
739785
summary: Export org members CSV
740786
description: |
741787
Export members of an organization as a CSV
788+
789+
<span class="oat"></span>
742790
tags:
743791
- orgs
744792
security:
@@ -812,6 +860,8 @@ paths:
812860
description: |
813861
Updates the role of a member in the organization.
814862
***Only users in the "owners" group of the organization can use this endpoint.***
863+
864+
<span class="oat"></span>
815865
tags:
816866
- orgs
817867
security:
@@ -850,6 +900,8 @@ paths:
850900
summary: Remove member from org
851901
description: |
852902
Removes the member from the org, ie. all groups in the org, unless they're the last owner
903+
904+
<span class="oat"></span>
853905
tags:
854906
- orgs
855907
security:
@@ -873,6 +925,8 @@ paths:
873925
summary: List org invites
874926
description: |
875927
Return all pending invites for a given org, only team owners can call this endpoint
928+
929+
<span class="oat"></span>
876930
tags:
877931
- invites
878932
security:
@@ -901,6 +955,8 @@ paths:
901955
- $ref: '#/components/parameters/org_name'
902956
get:
903957
summary: Get groups of an organization
958+
description: |
959+
<span class="oat"></span>
904960
tags:
905961
- groups
906962
security:
@@ -946,7 +1002,10 @@ paths:
9461002
$ref: '#/components/responses/not_found'
9471003
post:
9481004
summary: Create a new group
949-
description: Create a new group within an organization.
1005+
description: |
1006+
Create a new group within an organization.
1007+
1008+
<span class="oat"></span>
9501009
tags:
9511010
- groups
9521011
security:
@@ -982,6 +1041,8 @@ paths:
9821041
- $ref: '#/components/parameters/group_name'
9831042
get:
9841043
summary: Get a group of an organization
1044+
description: |
1045+
<span class="oat"></span>
9851046
tags:
9861047
- groups
9871048
security:
@@ -1001,6 +1062,8 @@ paths:
10011062
$ref: '#/components/responses/not_found'
10021063
put:
10031064
summary: Update the details for an organization group
1065+
description: |
1066+
<span class="oat"></span>
10041067
tags:
10051068
- groups
10061069
security:
@@ -1031,6 +1094,8 @@ paths:
10311094
$ref: '#/components/responses/not_found'
10321095
patch:
10331096
summary: Update some details for an organization group
1097+
description: |
1098+
<span class="oat"></span>
10341099
tags:
10351100
- groups
10361101
security:
@@ -1059,6 +1124,8 @@ paths:
10591124
$ref: '#/components/responses/not_found'
10601125
delete:
10611126
summary: Delete an organization group
1127+
description: |
1128+
<span class="oat"></span>
10621129
tags:
10631130
- groups
10641131
security:
@@ -1091,6 +1158,8 @@ paths:
10911158
description: |
10921159
List the members (users) that are in a group.
10931160
If user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails.
1161+
1162+
<span class="oat"></span>
10941163
tags:
10951164
- groups
10961165
responses:
@@ -1123,7 +1192,9 @@ paths:
11231192
parameters:
11241193
- $ref: '#/components/parameters/org_name'
11251194
- $ref: '#/components/parameters/group_name'
1126-
summary: Adds a member to a group
1195+
summary: Add a member to a group
1196+
description: |
1197+
<span class="oat"></span>
11271198
tags:
11281199
- groups
11291200
security:
@@ -1148,7 +1219,9 @@ paths:
11481219
- $ref: '#/components/parameters/group_name'
11491220
- $ref: '#/components/parameters/username'
11501221
delete:
1151-
summary: Removes a user from a group
1222+
summary: Remove a user from a group
1223+
description: |
1224+
<span class="oat"></span>
11521225
tags:
11531226
- groups
11541227
security:
@@ -1174,6 +1247,8 @@ paths:
11741247
summary: Cancel an invite
11751248
description: |
11761249
Mark the invite as cancelled so it doesn't show up on the list of pending invites
1250+
1251+
<span class="oat"></span>
11771252
tags:
11781253
- invites
11791254
security:
@@ -1199,6 +1274,8 @@ paths:
11991274
summary: Resend an invite
12001275
description: |
12011276
Resend a pending invite to the user, any org owner can resend an invite
1277+
1278+
<span class="oat"></span>
12021279
tags:
12031280
- invites
12041281
security:
@@ -1220,6 +1297,8 @@ paths:
12201297
summary: Bulk create invites
12211298
description: |
12221299
Create multiple invites by emails or DockerIDs. Only a team owner can create invites.
1300+
1301+
<span class="oat"></span>
12231302
tags:
12241303
- invites
12251304
requestBody:
@@ -2878,9 +2957,10 @@ x-tagGroups:
28782957
tags:
28792958
- resources
28802959
- rate-limiting
2960+
- authentication
28812961
- name: API
28822962
tags:
2883-
- authentication
2963+
- authentication-api
28842964
- access-tokens
28852965
- images
28862966
- audit-logs

‎layouts/_default/api-baseof.html‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,32 @@
1919
background-color: #086dd7;
2020
padding: 16px;
2121
}
22+
23+
.auth-tag,.pat,.oat {
24+
border-radius: 4px;
25+
color: #fff;
26+
padding: 5px;
27+
}
28+
29+
.pat {
30+
background-color: rgb(149, 80, 124);
31+
}
32+
33+
.pat::after {
34+
content: "personal access token";
35+
}
36+
37+
.oat::after {
38+
content: "org access token";
39+
}
40+
41+
.oat {
42+
background-color: rgb(24, 111, 175);
43+
}
44+
45+
.auth-tag:not(:last-child) {
46+
margin-right: 5px;
47+
}
2248
</style>
2349
</head>
2450

0 commit comments

Comments
 (0)