Skip to content

Commit 16774c1

Browse files
technicallyjoshtechnicallyjosh
committed
Improve auth docs and add oat tags
1 parent da9b5a7 commit 16774c1

File tree

2 files changed

+117
-9
lines changed

2 files changed

+117
-9
lines changed

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

Lines changed: 91 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,52 @@ 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+
This section describes the different types of authentication available.
54+
55+
# Types
56+
57+
These are the types of authentication available for the Docker Hub API.
58+
59+
Each authentication type should be used with the [Create access token](#tag/authentication-api/operation/AuthCreateAccessToken)
60+
route to obtain a bearer token to be used.
61+
62+
## Password
63+
Using a username and password is the most powerful, yet least secure way
64+
to authenticate with Docker as a user. It allows for access to resources
65+
for the user without scopes.
66+
67+
_In general, it is recommended to use a personal access token (PAT) instead._
68+
69+
_**This is not available if your organization has SSO enforced.**_
70+
71+
## Personal Access Token (PAT)
72+
Using a username and PAT is the most secure way to authenticate with
73+
Docker as a user. PATs are scoped to specific resources and scopes.
74+
75+
Currently a PAT is a more secure password due to limited functionality,
76+
but in the future we may add fine-grained access like organization
77+
access tokens for enhanced usage and security.
78+
79+
## Organization Access Token (OAT)
80+
Organization access tokens are scoped to specific resources and scopes
81+
within an organization and are managed by organization owners.
82+
83+
These tokens are meant for automation and are not meant to be used by
84+
users.
85+
86+
# Labels
87+
88+
These labels will show up on routes in this document that allow for bearer
89+
tokens issued from them to be used.
90+
91+
<span class="pat"></span>
92+
<span class="oat"></span>
93+
- name: authentication-api
94+
x-displayName: Authentication
95+
description: |
96+
The authentication endpoints allow you to authenticate with Docker Hub APIs.
97+
98+
For more information, see [Authentication](#tag/authentication).
5399
- name: access-tokens
54100
x-displayName: Personal Access Tokens
55101
description: |
@@ -110,7 +156,7 @@ paths:
110156
/v2/users/login:
111157
post:
112158
tags:
113-
- authentication
159+
- authentication-api
114160
summary: Create an authentication token
115161
operationId: PostUsersLogin
116162
security: []
@@ -123,7 +169,7 @@ paths:
123169
_**As of September 16, 2024, this route requires a personal access token (PAT) instead of a password if your organization has SSO enforced.**_
124170
125171
<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.
172+
<strong>Deprecated</strong>: Use [<a href="#tag/authentication-api/operation/AuthCreateAccessToken">Create access token</a>] instead.
127173
</div>
128174
requestBody:
129175
content:
@@ -148,7 +194,7 @@ paths:
148194
/v2/users/2fa-login:
149195
post:
150196
tags:
151-
- authentication
197+
- authentication-api
152198
summary: Second factor authentication
153199
operationId: PostUsers2FALogin
154200
security: []
@@ -183,7 +229,7 @@ paths:
183229
/v2/auth/token:
184230
post:
185231
tags:
186-
- authentication
232+
- authentication-api
187233
security: []
188234
summary: Create access token
189235
operationId: AuthCreateAccessToken
@@ -709,7 +755,9 @@ paths:
709755
get:
710756
summary: List org members
711757
description: |
712-
Returns a list of members for an organization"
758+
Returns a list of members for an organization
759+
760+
<span class="oat"></span>
713761
tags:
714762
- orgs
715763
security:
@@ -739,6 +787,8 @@ paths:
739787
summary: Export org members CSV
740788
description: |
741789
Export members of an organization as a CSV
790+
791+
<span class="oat"></span>
742792
tags:
743793
- orgs
744794
security:
@@ -812,6 +862,8 @@ paths:
812862
description: |
813863
Updates the role of a member in the organization.
814864
***Only users in the "owners" group of the organization can use this endpoint.***
865+
866+
<span class="oat"></span>
815867
tags:
816868
- orgs
817869
security:
@@ -850,6 +902,8 @@ paths:
850902
summary: Remove member from org
851903
description: |
852904
Removes the member from the org, ie. all groups in the org, unless they're the last owner
905+
906+
<span class="oat"></span>
853907
tags:
854908
- orgs
855909
security:
@@ -873,6 +927,8 @@ paths:
873927
summary: List org invites
874928
description: |
875929
Return all pending invites for a given org, only team owners can call this endpoint
930+
931+
<span class="oat"></span>
876932
tags:
877933
- invites
878934
security:
@@ -901,6 +957,8 @@ paths:
901957
- $ref: '#/components/parameters/org_name'
902958
get:
903959
summary: Get groups of an organization
960+
description: |
961+
<span class="oat"></span>
904962
tags:
905963
- groups
906964
security:
@@ -946,7 +1004,10 @@ paths:
9461004
$ref: '#/components/responses/not_found'
9471005
post:
9481006
summary: Create a new group
949-
description: Create a new group within an organization.
1007+
description: |
1008+
Create a new group within an organization.
1009+
1010+
<span class="oat"></span>
9501011
tags:
9511012
- groups
9521013
security:
@@ -982,6 +1043,8 @@ paths:
9821043
- $ref: '#/components/parameters/group_name'
9831044
get:
9841045
summary: Get a group of an organization
1046+
description: |
1047+
<span class="oat"></span>
9851048
tags:
9861049
- groups
9871050
security:
@@ -1001,6 +1064,8 @@ paths:
10011064
$ref: '#/components/responses/not_found'
10021065
put:
10031066
summary: Update the details for an organization group
1067+
description: |
1068+
<span class="oat"></span>
10041069
tags:
10051070
- groups
10061071
security:
@@ -1031,6 +1096,8 @@ paths:
10311096
$ref: '#/components/responses/not_found'
10321097
patch:
10331098
summary: Update some details for an organization group
1099+
description: |
1100+
<span class="oat"></span>
10341101
tags:
10351102
- groups
10361103
security:
@@ -1059,6 +1126,8 @@ paths:
10591126
$ref: '#/components/responses/not_found'
10601127
delete:
10611128
summary: Delete an organization group
1129+
description: |
1130+
<span class="oat"></span>
10621131
tags:
10631132
- groups
10641133
security:
@@ -1091,6 +1160,8 @@ paths:
10911160
description: |
10921161
List the members (users) that are in a group.
10931162
If user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails.
1163+
1164+
<span class="oat"></span>
10941165
tags:
10951166
- groups
10961167
responses:
@@ -1123,7 +1194,9 @@ paths:
11231194
parameters:
11241195
- $ref: '#/components/parameters/org_name'
11251196
- $ref: '#/components/parameters/group_name'
1126-
summary: Adds a member to a group
1197+
summary: Add a member to a group
1198+
description: |
1199+
<span class="oat"></span>
11271200
tags:
11281201
- groups
11291202
security:
@@ -1148,7 +1221,9 @@ paths:
11481221
- $ref: '#/components/parameters/group_name'
11491222
- $ref: '#/components/parameters/username'
11501223
delete:
1151-
summary: Removes a user from a group
1224+
summary: Remove a user from a group
1225+
description: |
1226+
<span class="oat"></span>
11521227
tags:
11531228
- groups
11541229
security:
@@ -1174,6 +1249,8 @@ paths:
11741249
summary: Cancel an invite
11751250
description: |
11761251
Mark the invite as cancelled so it doesn't show up on the list of pending invites
1252+
1253+
<span class="oat"></span>
11771254
tags:
11781255
- invites
11791256
security:
@@ -1199,6 +1276,8 @@ paths:
11991276
summary: Resend an invite
12001277
description: |
12011278
Resend a pending invite to the user, any org owner can resend an invite
1279+
1280+
<span class="oat"></span>
12021281
tags:
12031282
- invites
12041283
security:
@@ -1220,6 +1299,8 @@ paths:
12201299
summary: Bulk create invites
12211300
description: |
12221301
Create multiple invites by emails or DockerIDs. Only a team owner can create invites.
1302+
1303+
<span class="oat"></span>
12231304
tags:
12241305
- invites
12251306
requestBody:
@@ -2878,9 +2959,10 @@ x-tagGroups:
28782959
tags:
28792960
- resources
28802961
- rate-limiting
2962+
- authentication
28812963
- name: API
28822964
tags:
2883-
- authentication
2965+
- authentication-api
28842966
- access-tokens
28852967
- images
28862968
- 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)