Skip to content

bug: Fix OAuth Exchange docs #584

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 24, 2022
Merged

bug: Fix OAuth Exchange docs #584

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0217c57
bug: Fix OAuth Exchange docs
Dorthu Jan 14, 2022
25aecac
Fixes and add refresh workflow
bbiggerr Jan 24, 2022
d62a665
Clarify access token refresh
bbiggerr Jan 24, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 17 additions & 6 deletions openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,9 +82,9 @@ info:
| 2. Your application then redirects the user to Linode's [login 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 [login 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. |
| 3. The user logs into the login server with their username and password. | 3. The user logs into the login server with their username and password. |
| 4. The login server redirects the user to the specificed redirect URL with a temporary authorization `code` (exchange code) in the URL. | 4. The login 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 two hours. No `refresh_token` is issued. Therefore, once the `access_token` expires, a new one will need to be issued by having the user log in again. |
| 5. The application issues a POST request (*see below*) to the login server with the exchange code, `client_id`, and the client application's `client_secret`. | |
| 5. The application issues a POST request (*see additional details below*) to the login server with the exchange code, `client_id`, and the client application's `client_secret`. | |
| 6. The login server responds to the client application with a new OAuth `access_token` and `refresh_token`. The `access_token` is set to expire in two hours. | |
| 7. The `refresh_token` can be used by contacting the login server with the `client_id`, `client_secret`, `grant_type`, and `refresh_token` to get a new OAuth `access_token` and `refresh_token`. The new `access_token` is good for another two hours, and the new `refresh_token`, can be used to extend the session again by this same method. | |
| 7. The `refresh_token` can be used by contacting the login server with the `client_id`, `client_secret`, `grant_type`, and `refresh_token` to get a new OAuth `access_token` and `refresh_token`. The new `access_token` is good for another two hours, and the new `refresh_token` can be used to extend the session again by this same method (*see additional details below*). | |

#### OAuth Private Workflow - Additional Details

Expand All @@ -103,7 +103,6 @@ info:

| PARAMETER | DESCRIPTION |
|-----------|-------------|
| grant_type | The grant type you're using for renewal. Currently only the string "refresh_token" is accepted. |
| client_id | Your app's client ID. |
| client_secret | Your app's client secret. |
| code | The code you just received from the redirect. |
Expand All @@ -113,19 +112,31 @@ info:
```json
{
"scope": "linodes:read_write",
"access_token": "03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c"
"access_token": "03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c",
"refresh_token": "f2ec9712e616fdb5a2a21aa0e88cfadea7502ebc62cf5bd758dbcd65e1803bad",
"token_type": "bearer",
"expires_in": 7200,
"expires_in": 7200
}
```

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

```
Authorization: Bearer 03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c
```

This `access_token` is set to expire in two hours. To refresh access prior to expiration, make another request to the same URL with the following parameters in the POST body:

| PARAMETER | DESCRIPTION |
|-----------|-------------|
| grant_type | The grant type you're using. Use "refresh_token" when refreshing access. |
| client_id | Your app's client ID. |
| client_secret | Your app's client secret. |
| refresh_token | The `refresh_token` received from the previous response. |

You'll get another response with an updated `access_token` and `refresh_token`, which can then be used to refresh access again.

#### OAuth Reference

| Security Scheme Type | OAuth 2.0 |
Expand Down