diff --git a/drama/templates/api.html b/drama/templates/api.html index d9143f734..2668ba41f 100644 --- a/drama/templates/api.html +++ b/drama/templates/api.html @@ -8,7 +8,55 @@ {% block content %}
{% 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: + ++ 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()) ++ +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. @@ -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: * 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 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 -Send your user to `https://rdrama.net/oauth/authorize`, with the following URL parameters: - -* `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. +Send your user to `https://rdrama.net/authorize/?client_id=YOUR_CLIENT_ID` 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 -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. -* `state` - The state token from earlier. +## Step 4: Using the Access Token -Validate the state token. How you do this is up to you. - -## 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. +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:
import requests - code=request.args.get("code") - headers={"User-Agent": "sex"} - url="/oauth/grant" - data={"client_id": my_client_id, - "client_secret": my_client_secret, - "grant_type": "code", - "code": code - } + headers={"Authorization": "access_token_goes_here", "User-Agent": "sex"} - r=requests.post(url, headers=headers, data=data) - - print(r.json()) -- -If everything is good, we will respond with the following (example) JSON body: - -
- { - "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 - } -- -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: - -
- import requests - - headers={"Authorization": "Bearer " + access_token, - "User-Agent": "{{"SITE_NAME" | app_config}} Reader v1 by @carpathianflorist"} - url="/" + url="https://rdrama.net/@carpathianflorist" r=requests.get(url, headers=headers) print(r.json())-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 %}