Skip to content

Commit 5ed3357

Browse files
DorthuDorthu
authored
Merge pull request #2579 from RobertDeRose/feature/oauth-apps
Feature/oauth apps
2 parents 831ef48 + 34a543c commit 5ed3357

File tree

2 files changed

+177
-126
lines changed

2 files changed

+177
-126
lines changed

‎docs/src/data/endpoints/account.yaml

Lines changed: 36 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -5,105 +5,6 @@ description: >
55
Account endpoints provide a means of manipulating your account, including users,
66
OAuth Clients and Tokens, and Events.
77
endpoints:
8-
/account/tokens:
9-
group: Tokens
10-
description: >
11-
Manage OAuth Tokens created for your user.
12-
methods:
13-
GET:
14-
response: oauthtoken
15-
paginationKey: tokens
16-
oauth: tokens:view
17-
description: >
18-
Get a list of all OAuth Tokens active for your user. This includes first-party (manager) tokens,
19-
third-party OAuth Tokens, and Personal Access Tokens.
20-
examples:
21-
curl: |
22-
curl -H "Authorization: Bearer $TOKEN" \
23-
https://$api_root/$version/account/tokens
24-
python: |
25-
my_tokens = client.account.get_tokens()
26-
POST:
27-
oauth: tokens:create
28-
dangerous: true
29-
description: >
30-
Creates a new Personal Access Token for your user with the given scopes and expiry. This token
31-
can subsequently be used to access the API and make any requests it has OAuth Scopes for.
32-
params:
33-
label:
34-
type: String
35-
value: my-token
36-
optional: true
37-
description: >
38-
The label for this Personal Access Token. For your reference only.
39-
expiry:
40-
type: Datetime
41-
value: 2017-12-31 01:00:00
42-
optional: true
43-
description: >
44-
If provided, when this Personal Access Token will expire. If omitted, the resulting
45-
token will be valid until it is revoked.
46-
scopes:
47-
type: String
48-
value: linodes:view
49-
optional: true
50-
description: >
51-
The OAuth Scopes this token will be created with. If omitted, the resulting token
52-
will have all OAuth Scopes.
53-
examples:
54-
curl: |
55-
curl -H "Content-Type: application/json" \
56-
-H "Authorization: Bearer $TOKEN" \
57-
-X POST -d '{
58-
"scopes": "linodes:view;domains:view"
59-
}' \
60-
https://$api_root/$version/account/tokens
61-
python: |
62-
from linode import OAuthScopes
63-
new_token = client.account.create_personal_access_token(scopes=[OAuthScopes.Linodes.view, OAuthScopes.Domains.view])
64-
/account/tokens/$id:
65-
group: Tokens
66-
type: resource
67-
description: >
68-
Manage individual OAuth Tokens for your user.
69-
methods:
70-
GET:
71-
response: oauthtoken
72-
oauth: tokens:view
73-
description: >
74-
Get a single token.
75-
examples:
76-
curl: |
77-
curl -H "Authorization: Bearer $TOKEN" \
78-
https://$api_root/$version/account/tokens/123
79-
python: |
80-
my_token = linode.OAuthToken(client, 123)
81-
PUT:
82-
oauth: tokens:modify
83-
description: >
84-
Edit a token's label.
85-
examples:
86-
curl: |
87-
curl -H "Content-Type: application/json" \
88-
-H "Authorization: Bearer $TOKEN" \
89-
-X PUT -d '{
90-
"label": "test-new-label"
91-
}' \
92-
https://$api_root/$version/account/tokens/123
93-
python: |
94-
my_token.label = 'test-new-label'
95-
my_token.save()
96-
DELETE:
97-
oauth: tokens:delete
98-
description: >
99-
Expire an OAuth Token for your user.
100-
examples:
101-
curl: |
102-
curl -H "Authorization: Bearer $TOKEN" \
103-
-X DELETE \
104-
https://$api_root/$version/account/tokens/123
105-
python: |
106-
my_token.delete()
1078
/account/settings:
1089
group: Settings
10910
type: resource
@@ -151,8 +52,8 @@ endpoints:
15152
my_settings.country = 'US'
15253
my_settings.email = '[email protected]'
15354
my_settings.save()
154-
/account/clients:
155-
group: Clients
55+
/account/oauth-clients:
56+
group: OAuth Clients
15657
authenticated: true
15758
description: >
15859
Manage the collection of OAuth client applications your account may access.
@@ -162,11 +63,13 @@ endpoints:
16263
paginationKey: clients
16364
oauth: clients:view
16465
description: >
165-
Returns a list of clients.
66+
Returns a list of OAuth clients for your user. If you are an admin
67+
user, you will see all OAuth clients associated with all users on your
68+
account.
16669
examples:
16770
curl: |
16871
curl -H "Authorization: Bearer $TOKEN" \
169-
https://$api_root/$version/account/clients
72+
https://$api_root/$version/account/oauth-clients
17073
python: |
17174
my_clients = client.account.get_oauth_clients()
17275
POST:
@@ -182,6 +85,11 @@ endpoints:
18285
description: A URL to redirect to after the OAuth flow has completed.
18386
type: String
18487
limit: "1-512 characters"
88+
public:
89+
description: Whether this client is intended will use the implicit
90+
OAuth flow because it cannot safely store the client_secrete.
91+
An example of this would be a Single-Page Application (SPA) for
92+
the Web.
18593
examples:
18694
curl: |
18795
curl -H "Content-Type: application/json" \
@@ -190,15 +98,16 @@ endpoints:
19098
"label": "Example app",
19199
"redirect_uri": "https://oauthreturn.example.org/",
192100
}' \
193-
https://$api_root/$version/account/clients
101+
https://$api_root/$version/account/oauth-clients
194102
python: |
195103
new_client = client.account.create_oauth_client('Example app', 'https://oauthreturn.example.org/')
196-
/account/clients/$id:
197-
group: Clients
104+
/account/oauth-clients/$id:
105+
group: OAuth Clients
198106
type: resource
199107
authenticated: true
200108
description: >
201109
Manage a particular OAuth client application your account may access.
110+
Admin users can manage any OAuth client associated with this account.
202111
methods:
203112
GET:
204113
response: client
@@ -208,7 +117,7 @@ endpoints:
208117
examples:
209118
curl: |
210119
curl -H "Authorization: Bearer $TOKEN" \
211-
https://$api_root/$version/account/clients/$client_id
120+
https://$api_root/$version/account/oauth-clients/$client_id
212121
python: |
213122
my_client = linode.OAuthClient(client, 123)
214123
PUT:
@@ -223,7 +132,7 @@ endpoints:
223132
"name": "Updated app name",
224133
"redirect_uri": "https://newredirect.example.org/",
225134
}' \
226-
https://$api_root/$version/account/clients/$client_id
135+
https://$api_root/$version/account/oauth-clients/$client_id
227136
python: |
228137
my_client.name = 'Updated app name'
229138
my_client.save()
@@ -232,16 +141,18 @@ endpoints:
232141
dangerous: true
233142
description: >
234143
Delete this OAuth application. This action cannot be undone.
144+
Once an OAuth Application is deleted, all associated OAuth
145+
tokens that were generated on its behalf are expired as well.
235146
examples:
236147
curl: |
237148
curl -H "Authorization: Bearer $TOKEN" \
238149
-X DELETE \
239-
https://$api_root/$version/account/clients/$client_id
150+
https://$api_root/$version/account/oauth-clients/$client_id
240151
python: |
241152
my_client = linode.OAuthClient(client, 123)
242153
my_client.delete()
243-
/account/clients/$id/reset_secret:
244-
group: Clients
154+
/account/oauth-clients/$id/reset_secret:
155+
group: OAuth Clients
245156
type: Action
246157
authenticated: true
247158
description: >
@@ -255,12 +166,12 @@ endpoints:
255166
curl -H "Content-Type: application/json" \
256167
-H "Authorization: Bearer $TOKEN" \
257168
-X POST \
258-
https://$api_root/$version/account/clients/$client_id/reset_secret
169+
https://$api_root/$version/account/oauth-clients/$client_id/reset_secret
259170
python: |
260171
my_client = linode.OAuthClient(client, 123)
261172
new_secret = my_client.reset_secret()
262-
/account/clients/$id/thumbnail:
263-
group: Clients
173+
/account/oauth-clients/$id/thumbnail:
174+
group: OAuth Clients
264175
type: Action
265176
authenticated: true
266177
description: >
@@ -273,7 +184,7 @@ endpoints:
273184
examples:
274185
curl: |
275186
curl -H "Authorization: Bearer $TOKEN" \
276-
https://$api_root/$version/account/clients/$client_id/thumbnail
187+
https://$api_root/$version/account/oauth-clients/$client_id/thumbnail
277188
python: |
278189
img = my_client.get_thumbnail()
279190
@@ -290,7 +201,7 @@ endpoints:
290201
-H "Authorization: Bearer $TOKEN" \
291202
-X PUT \
292203
--data-binary "@/path/to/image"
293-
https://$api_root/$version/account/clients/$client_id/thumbnail
204+
https://$api_root/$version/account/oauth-clients/$client_id/thumbnail
294205
python: |
295206
my_client = linode.OAuthClient(client, 123)
296207
my_client.set_thumbnail('/path/to/image')
@@ -441,8 +352,8 @@ endpoints:
441352
442353
my_user.grants.global.add_linodes = True
443354
my_user.grants.save()
444-
/account/clients:
445-
group: Clients
355+
/account/oauth-clients:
356+
group: OAuth Clients
446357
authenticated: true
447358
description: >
448359
Manage the collection of OAuth client applications your account may access.
@@ -456,7 +367,7 @@ endpoints:
456367
examples:
457368
curl: |
458369
curl -H "Authorization: Bearer $TOKEN" \
459-
https://$api_root/$version/account/clients
370+
https://$api_root/$version/account/oauth-clients
460371
POST:
461372
oauth: clients:create
462373
description: >
@@ -478,9 +389,9 @@ endpoints:
478389
"name": "Example app",
479390
"redirect_uri": "https://oauthreturn.example.org/",
480391
}' \
481-
https://$api_root/$version/account/clients
482-
/account/clients/$id:
483-
group: Clients
392+
https://$api_root/$version/account/oauth-clients
393+
/account/oauth-clients/$id:
394+
group: OAuth Clients
484395
type: resource
485396
authenticated: true
486397
description: >
@@ -494,7 +405,7 @@ endpoints:
494405
examples:
495406
curl: |
496407
curl -H "Authorization: Bearer $TOKEN" \
497-
https://$api_root/$version/account/clients/$client_id
408+
https://$api_root/$version/account/oauth-clients/$client_id
498409
PUT:
499410
oauth: clients:modify
500411
description: >
@@ -507,7 +418,7 @@ endpoints:
507418
"name": "Updated app name",
508419
"redirect_uri": "https://newredirect.example.org/",
509420
}' \
510-
https://$api_root/$version/account/clients/$client_id
421+
https://$api_root/$version/account/oauth-clients/$client_id
511422
DELETE:
512423
oauth: clients:delete
513424
dangerous: true
@@ -517,7 +428,7 @@ endpoints:
517428
curl: |
518429
curl -H "Authorization: Bearer $TOKEN" \
519430
-X DELETE \
520-
https://$api_root/$version/account/clients/$client_id
431+
https://$api_root/$version/account/oauth-clients/$client_id
521432
/account/events:
522433
group: Events
523434
authenticated: true

0 commit comments

Comments
 (0)