fdfd
parent
6fcb219a9f
commit
a4889fc79d
|
@ -8,7 +8,55 @@
|
||||||
{% block content %}
|
{% block content %}
|
||||||
<pre></pre>
|
<pre></pre>
|
||||||
{% filter markdown %}
|
{% filter markdown %}
|
||||||
# OAuth2
|
# API Guide for Bots
|
||||||
|
|
||||||
|
This page explains how to obtain and use an access token.
|
||||||
|
|
||||||
|
## Step 1: Create your Application
|
||||||
|
|
||||||
|
In the [apps tab of {{"SITE_NAME" | app_config}} settings](/settings/apps), fill in and submit the form to request an access token. You will need:
|
||||||
|
|
||||||
|
* an application name
|
||||||
|
* a Redirect URI. May not use HTTP unless using localhost (use HTTPS instead).
|
||||||
|
* a brief description of what your bot is intended to do
|
||||||
|
|
||||||
|
Don't worry too much about accuracy; you will be able to change all of these later.
|
||||||
|
|
||||||
|
{{"SITE_NAME" | app_config}} administrators will review and approve or deny your request for an access token. You'll know when your request has been approved when you get a private message with an access token tied to your account.
|
||||||
|
|
||||||
|
DO NOT reveal your Client ID or Access Token. Anyone with these information will be able to pretend to be you. You are responsible for keeping them a secret!
|
||||||
|
|
||||||
|
## Step 2: Using the Access Token
|
||||||
|
|
||||||
|
To use the access token, include the following header in subsequent API requests to {{"SITE_NAME" | app_config}}: `Authorization: access_token_goes_here`
|
||||||
|
|
||||||
|
Python example:
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
import requests
|
||||||
|
|
||||||
|
headers={"Authorization": "access_token_goes_here", "User-Agent": "sex"}
|
||||||
|
|
||||||
|
url="https://rdrama.net/@carpathianflorist"
|
||||||
|
|
||||||
|
r=requests.get(url, headers=headers)
|
||||||
|
|
||||||
|
print(r.json())
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
The expected result of this would be a large JSON representation of the posts posted by @carpathianflorist
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
# API Guide for Applications
|
||||||
|
|
||||||
|
|
||||||
The OAuth2 authorization flow is used to enable users to authorize third-party applications to access their {{"SITE_NAME" | app_config}} account without having to provide their login information to the application.
|
The OAuth2 authorization flow is used to enable users to authorize third-party applications to access their {{"SITE_NAME" | app_config}} account without having to provide their login information to the application.
|
||||||
|
|
||||||
|
@ -19,97 +67,45 @@ This page explains how to obtain API application keys, how to prompt a user for
|
||||||
In the [apps tab of {{"SITE_NAME" | app_config}} settings](/settings/apps), fill in and submit the form to request new API keys. You will need:
|
In the [apps tab of {{"SITE_NAME" | app_config}} settings](/settings/apps), fill in and submit the form to request new API keys. You will need:
|
||||||
|
|
||||||
* an application name
|
* an application name
|
||||||
* a Redirect URI, or a comma-separated list of redirect URIs. May not use HTTP unless using localhost (use HTTPS instead).
|
* a Redirect URI. May not use HTTP unless using localhost (use HTTPS instead).
|
||||||
* a brief description of what your application is intended to do
|
* a brief description of what your application is intended to do
|
||||||
|
|
||||||
Don't worry too much about accuracy; you will be able to change all of these later.
|
Don't worry too much about accuracy; you will be able to change all of these later.
|
||||||
|
|
||||||
{{"SITE_NAME" | app_config}} administrators will review and approve or deny your request for API keys. You'll know when your request has been approved when a client ID and secret appear in your application information.
|
{{"SITE_NAME" | app_config}} administrators will review and approve or deny your request for API keys. You'll know when your request has been approved when you get a private message with an access token tied to your account.
|
||||||
|
|
||||||
DO NOT reveal your Client Secret. Anyone with your Client Secret will be able to pretend to be you. You are responsible for keeping your Client Secret a secret!
|
DO NOT reveal your Client ID or Access Token. Anyone with these information will be able to pretend to be you. You are responsible for keeping them a secret!
|
||||||
|
|
||||||
## Step 2: Prompt Your User for Authorization
|
## Step 2: Prompt Your User for Authorization
|
||||||
|
|
||||||
Send your user to `https://rdrama.net/oauth/authorize`, with the following URL parameters:
|
Send your user to `https://rdrama.net/authorize/?client_id=YOUR_CLIENT_ID`
|
||||||
|
|
||||||
* `client_id` - Your application's Client ID
|
|
||||||
* `redirect_uri` - The redirect URI (or one of the URIs) specified in your application information. Must not use HTTP unless using localhost (use HTTPS instead).
|
|
||||||
* `state` - This is your own anti-cross-site-forgery token. We don't do anything with this, except give it to the user to pass back to you later. You are responsible for generating and validating the state token.
|
|
||||||
* `scope` - A comma-separated list of permission scopes that you are requesting. Valid scopes are: `identity`, `create`, `read`, `update`, `delete` and `vote`.
|
|
||||||
* `permanent` - optional. Set to `true` if you are requesting indefinite access. Omit if not.
|
|
||||||
|
|
||||||
If done correctly, the user will see that your application wants to access their {{"SITE_NAME" | app_config}} account, and be prompted to approve or deny the request.
|
If done correctly, the user will see that your application wants to access their {{"SITE_NAME" | app_config}} account, and be prompted to approve or deny the request.
|
||||||
|
|
||||||
## Step 3: Catch the redirect
|
## Step 3: Catch the redirect
|
||||||
|
|
||||||
The user clicks "Authorize". {{"SITE_NAME" | app_config}} will redirect the user's browser to GET the designated redirect URI. The following URL parameters will be included, which your server should process:
|
The user clicks "Authorize". {{"SITE_NAME" | app_config}} will redirect the user's browser to GET the designated redirect URI. The access token URL parameter will be included in the redirect, which your server should process.
|
||||||
|
|
||||||
* `code` - a **single-use** authorization code.
|
## Step 4: Using the Access Token
|
||||||
* `state` - The state token from earlier.
|
|
||||||
|
|
||||||
Validate the state token. How you do this is up to you.
|
To use the access token, include the following header in subsequent API requests to {{"SITE_NAME" | app_config}}: `Authorization: access_token_goes_here`
|
||||||
|
|
||||||
## Step 4: Exchange code for access token
|
|
||||||
|
|
||||||
Make a POST request to `https://rdrama.net/oauth/grant`. Include the following form parameters:
|
|
||||||
|
|
||||||
* `client_id` - Your application's Client ID
|
|
||||||
* `client_secret` - Your application's Client Secret
|
|
||||||
* `grant_type` - Set to the word "code"
|
|
||||||
* `code` - The `code` parameter that was given to you in the previous step.
|
|
||||||
|
|
||||||
Python example:
|
Python example:
|
||||||
|
|
||||||
<pre>
|
<pre>
|
||||||
import requests
|
import requests
|
||||||
code=request.args.get("code")
|
|
||||||
|
|
||||||
headers={"User-Agent": "sex"}
|
headers={"Authorization": "access_token_goes_here", "User-Agent": "sex"}
|
||||||
url="/oauth/grant"
|
|
||||||
data={"client_id": my_client_id,
|
|
||||||
"client_secret": my_client_secret,
|
|
||||||
"grant_type": "code",
|
|
||||||
"code": code
|
|
||||||
}
|
|
||||||
|
|
||||||
r=requests.post(url, headers=headers, data=data)
|
url="https://rdrama.net/@carpathianflorist"
|
||||||
|
|
||||||
print(r.json())
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
If everything is good, we will respond with the following (example) JSON body:
|
|
||||||
|
|
||||||
<pre>
|
|
||||||
{
|
|
||||||
"access_token": #Access token
|
|
||||||
"scopes": #Comma-separated list of scopes included in authorization
|
|
||||||
"expires_at": #Unix epoch integer time at which access token expires
|
|
||||||
"token_type": "Bearer"
|
|
||||||
"refresh_token": #This key is omitted in temporary authorizations
|
|
||||||
}
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
Store the access and refresh tokens. You should also store expiration timestamp and the scopes list, so that you pre-emptively avoid sending requests to {{"SITE_NAME" | app_config}} that won't be accepted.
|
|
||||||
|
|
||||||
## Step 5: Using the Access Token
|
|
||||||
|
|
||||||
To use the access token, include the following header in subsequent API requests to {{"SITE_NAME" | app_config}}: `Authorization: Bearer access_token_goes_here`
|
|
||||||
|
|
||||||
Python example, presuming that the application has obtained a valid `read` authorization:
|
|
||||||
|
|
||||||
<pre>
|
|
||||||
import requests
|
|
||||||
|
|
||||||
headers={"Authorization": "Bearer " + access_token,
|
|
||||||
"User-Agent": "{{"SITE_NAME" | app_config}} Reader v1 by @carpathianflorist"}
|
|
||||||
url="/"
|
|
||||||
|
|
||||||
r=requests.get(url, headers=headers)
|
r=requests.get(url, headers=headers)
|
||||||
|
|
||||||
print(r.json())
|
print(r.json())
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
The expected result of this would be a large JSON representation of the submissions that make up the user's personal front page.
|
The expected result of this would be a large JSON representation of the submissions submitted by @carpathianflorist
|
||||||
|
|
||||||
|
|
||||||
{% endfilter %}
|
{% endfilter %}
|
||||||
<pre>
|
<pre>
|
||||||
|
|
Loading…
Reference in New Issue