Skip to content

Commit 39d2309

Browse files
nmelehannmelehan
committed
Copy edit OAuth section
Various typo fixes and copy edits Added more definitions for public vs private clients Added H3 subsection headers: - OAuth Workflow - OAuth Private Workflow - Additional Details
1 parent f068e68 commit 39d2309

File tree

1 file changed

+44
-32
lines changed

1 file changed

+44
-32
lines changed

‎openapi.yaml

Lines changed: 44 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ info:
3737
generated from the
3838
<a target="_top" href="https://cloud.linode.com/profile/tokens">Linode Cloud Manager</a>.
3939

40-
All scopes for the OAuth security model (defined below) apply to this
40+
All scopes for the OAuth security model ([defined below](#o-auth)) apply to this
4141
security model as well.
4242

4343
### Authentication
@@ -47,49 +47,59 @@ info:
4747
| **HTTP Authorization Scheme** | bearer |
4848

4949
## OAuth
50-
If all you need is a Personal Access Token, feel free to skip ahead to the next section.
50+
If you only need to access the Linode API for personal uses,
51+
we recommend that you create a [personal access token](#personal-access-token).
52+
If you're designing an application that can authenticate with an arbitrary Linode user, then
53+
you should use the OAuth 2.0 workflows presented in this section.
5154

52-
For more help on OAuth see our guide on [How to Create an OAuth App with the Linode Python API Library](https://www.linode.com/docs/platform/api/how-to-create-an-oauth-app-with-the-linode-python-api-library/#oauth-2-authentication-exchange).
55+
For a more detailed example of an OAuth 2.0 implementation, see our guide on [How to Create an OAuth App with the Linode Python API Library](https://www.linode.com/docs/platform/api/how-to-create-an-oauth-app-with-the-linode-python-api-library/#oauth-2-authentication-exchange).
5356

54-
Before you begin, you need to creat an OAuth client. You can do this [with the API](https://developers.linode.com/api/v4/account-oauth-clients/#post) or [via the Cloud Manager](https://cloud.linode.com/profile/clients).
57+
Before you implement OAuth in your application, you first need to create an OAuth client. You can do this [with the Linode API](https://developers.linode.com/api/v4/account-oauth-clients/#post) or [via the Cloud Manager](https://cloud.linode.com/profile/clients):
5558

56-
- For this you will pass a `label` and a `redirect_uri`.
57-
- The return from this endpoint will give you a `client_id` and a `secret`.
58-
- You can choose to make this `public`. The workflow below is split for public and private paths where they diverge.
59+
- When creating the client, you'll supply a `label` and a `redirect_uri` (referred to as the Callback URL in the Cloud Manager).
60+
- The response from this endpoint will give you a `client_id` and a `secret`.
61+
- Clients can be public or private, and are private by default. You can choose to make the client public when it is created.
62+
- A private client is used with applications which can securely store the client secret (that is, the secret returned to you when you first created the client). For example, an application running on a secured server that only the developer has access to would use a private OAuth client. This is also called a confidential client in some OAuth documentation.
63+
- A public client is used with applications where the client secret is not guaranteed to be secure. For example, a native app running on a user's computer may not be able to keep the client secret safe, as a user could potentially inspect the source of the application. So, native apps or apps that run in a user's browser should use a public client.
64+
- Public and private clients follow different workflows, as described below.
5965

60-
The OAuth workflow is a series of exchanges between your third-party app and Linode used
66+
### OAuth Workflow
67+
68+
The OAuth workflow is a series of exchanges between your third-party app and Linode. The workflow is used
6169
to authenticate a User before an application can start making API calls on the User's behalf.
6270

6371
| PRIVATE WORKFLOW | PUBLIC WORKFLOW |
64-
|------------------|-----------------|
72+
|------------------|------------------|
6573
| 1. The User visits the application's website and is directed to login with Linode. | 1. The User visits the application's website and is directed to login with Linode. |
66-
| 2. Your application then redirects the user to Linode's [authentication server](https://login.linode.com) with the client application's `client_id` and requested OAuth `scope`, which appear in the URL of the login page. | 2. Your application then redirects the user to Linode's [authentication server](https://login.linode.com) with the client application's `client_id` and requested OAuth `scope`, which appear in the URL of the login page. |
74+
| 2. Your application then redirects the user to Linode's [authentication server](https://login.linode.com) with the client application's `client_id` and requested OAuth `scope`, which should appear in the URL of the login page. | 2. Your application then redirects the user to Linode's [authentication server](https://login.linode.com) with the client application's `client_id` and requested OAuth `scope`, which should appear in the URL of the login page. |
6775
| 3. The user logs into the authorization server with their username and password. | 3. The user logs into the authorization server with their username and password. |
68-
| 4. The authorization server redirects the user to the specificed redirect URL with a temporary authorization `code` (exchange code) in the URL. | 4. The authorization server redirects the user back to your applaction with an OAuth token in the URL hash. This is temporary and expires in 2 hours without a `refresh_token`. |
69-
| 5. The application issues a POST request (*see below*) to the authentication server with the exchange code, `client_id`, and the client application's `client_secret`. In return, the server returns an OAuth token and `refresh_token`. | |
70-
| 6. The authentication server responds to the client application with a new OAuth `access_token`. `access_token` is set to expire in 2 hours. | |
76+
| 4. The authorization server redirects the user to the specificed redirect URL with a temporary authorization `code` (exchange code) in the URL. | 4. The authorization server redirects the user back to your application with an OAuth `access_token` embedded in the redirect URL's hash. This is temporary and expires in 2 hours without a `refresh_token`. |
77+
| 5. The application issues a POST request (*see below*) to the authentication server with the exchange code, `client_id`, and the client application's `client_secret`. | |
78+
| 6. The authentication server responds to the client application with a new OAuth `access_token` and `refresh_token`. The `access_token` is set to expire in 2 hours. | |
7179
| 7. The `refresh_token` can be used to get a new OAuth `access_token`, good for another 2 hours, and a new `refresh_token`, which you can use to extend the session again by this same method, by contacting the authentication server again with the `client_id`, `client_secret`, and `refresh_token`. | |
7280

73-
The following is more information for the private workflow expanding on step 5 and beyond.
81+
### OAuth Private Workflow - Additional Details
7482

75-
Once the User has logged into Linode and you have received an exchange code,
76-
you will need to trade that exchange code for an Authorization token. You
77-
do this by making an HTTP POST request to the following address:
83+
The following information expands on steps 5 through 7 of the private workflow:
7884

79-
```
80-
https://login.linode.com/oauth/token
81-
```
85+
Once the User has logged into Linode and you have received an exchange code,
86+
you will need to trade that exchange code for an `access_token` and `refresh_token`. You
87+
do this by making an HTTP POST request to the following address:
8288

83-
Make this request as `application/x-www-form-urlencoded` or as
84-
`multipart/form-data` and include the following parameters in the POST body:
89+
```
90+
https://login.linode.com/oauth/token
91+
```
8592

86-
| PARAMETER | DESCRIPTION |
87-
|-----------|-------------|
88-
| client_id | Your app's client ID. |
89-
| client_secret | Your app's client secret. |
90-
| code | The code you just received from the redirect |
93+
Make this request as `application/x-www-form-urlencoded` or as
94+
`multipart/form-data` and include the following parameters in the POST body:
9195

92-
You'll get a reponse like this:
96+
| PARAMETER | DESCRIPTION |
97+
|-----------|-------------|
98+
| client_id | Your app's client ID. |
99+
| client_secret | Your app's client secret. |
100+
| code | The code you just received from the redirect. |
101+
102+
You'll get a response like this:
93103

94104
```json
95105
{
@@ -100,18 +110,20 @@ info:
100110
}
101111
```
102112

103-
Included in the reponse is `access_token`. With this token, you can proceed to make
113+
Included in the reponse is an `access_token`. With this token, you can proceed to make
104114
authenticated HTTP requests to the API by adding this header to each request:
105115

106116
```
107117
Authorization: Bearer 03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c
108118
```
109119

110-
### Authentication
120+
### OAuth Reference
111121

112-
| Security Scheme Type: | Oauth2 |
122+
| Security Scheme Type | OAuth 2.0 |
113123
|-----------------------|--------|
114-
| **AuthorizationCode Oauth Flow** | **Authorization URL:** https://login.linode.com/oauth/authorize<br />**Token URL:** https://login.linode.com/oauth/token<br />**Scopes:**<br /><ul><li>`account:read_only` - Allows access to GET information about your Account.</li><li>`account:read_write` - Allows access to all endpoints related to your Account.</li><li>`domains:read_only` - Allows access to GET Domains on your Account.</li><li>`domains:read_write` - Allows access to all Domain endpoints.</li><li>`events:read_only` - Allows access to GET your Events.</li><li>`events:read_write` - Allows access to all endpoints related to your Events.</li><li>`images:read_only` - Allows access to GET your Images.</li><li>`images:read_write` - Allows access to all endpoints related to your Images.</li><li>`ips:read_only` - Allows access to GET your ips.</li><li>`ips:read_write` - Allows access to all endpoints related to your ips.</li><li>`linodes:read_only` - Allows access to GET Linodes on your Account.</li><li>`linodes:read_write` - Allow access to all endpoints related to your Linodes.</li><li>`lke:read_only` - Allows access to GET LKE Clusters on your Account.</li><li>`lke:read_write` - Allows access to all endpoints related to LKE Clusters on your Account.</li><li>`longview:read_only` - Allows access to GET your Longview Clients.</li><li>`longview:read_write` - Allows access to all endpoints related to your Longview Clients.</li><li>`nodebalancers:read_only` - Allows access to GET NodeBalancers on your Account.</li><li>`nodebalancers:read_write` - Allows access to all NodeBalancer endpoints.</li><li>`stackscripts:read_only` - Allows access to GET your StackScripts.</li><li>`stackscripts:read_write` - Allows access to all endpoints related to your StackScripts.</li><li>`volumes:read_only` - Allows access to GET your Volumes.</li><li>`volumes:read_write` - Allows access to all endpoints related to your Volumes.</li></ul><br />|
124+
| **Authorization URL** | https://login.linode.com/oauth/authorize |
125+
| **Token URL** | https://login.linode.com/oauth/token |
126+
| **Scopes** | <ul><li>`account:read_only` - Allows access to GET information about your Account.</li><li>`account:read_write` - Allows access to all endpoints related to your Account.</li><li>`domains:read_only` - Allows access to GET Domains on your Account.</li><li>`domains:read_write` - Allows access to all Domain endpoints.</li><li>`events:read_only` - Allows access to GET your Events.</li><li>`events:read_write` - Allows access to all endpoints related to your Events.</li><li>`images:read_only` - Allows access to GET your Images.</li><li>`images:read_write` - Allows access to all endpoints related to your Images.</li><li>`ips:read_only` - Allows access to GET your ips.</li><li>`ips:read_write` - Allows access to all endpoints related to your ips.</li><li>`linodes:read_only` - Allows access to GET Linodes on your Account.</li><li>`linodes:read_write` - Allow access to all endpoints related to your Linodes.</li><li>`lke:read_only` - Allows access to GET LKE Clusters on your Account.</li><li>`lke:read_write` - Allows access to all endpoints related to LKE Clusters on your Account.</li><li>`longview:read_only` - Allows access to GET your Longview Clients.</li><li>`longview:read_write` - Allows access to all endpoints related to your Longview Clients.</li><li>`nodebalancers:read_only` - Allows access to GET NodeBalancers on your Account.</li><li>`nodebalancers:read_write` - Allows access to all NodeBalancer endpoints.</li><li>`stackscripts:read_only` - Allows access to GET your StackScripts.</li><li>`stackscripts:read_write` - Allows access to all endpoints related to your StackScripts.</li><li>`volumes:read_only` - Allows access to GET your Volumes.</li><li>`volumes:read_write` - Allows access to all endpoints related to your Volumes.</li></ul><br />|
115127

116128
# Requests
117129

0 commit comments

Comments
 (0)