Doc improvements

* Reorganize some main readme contents into separate docs * Add full bot authentication guide * Add screenshots and web interface section Some link fixes and clarifications Fix another link Fix another link More doc cleanup More doc cleanup More doc cleanup Add link to docs in main readme summary
2026-04-19 03:00:07 -04:00 · 2021-07-28 13:15:37 -04:00
parent c1ab3b11f4
commit 0afd87ab1b
8 changed files with 267 additions and 159 deletions
--- a/docs/botAuthentication.md
+++ b/docs/botAuthentication.md
@@ -0,0 +1,94 @@
+**Note:** This is for **bot operators.** If you are a subreddit moderator check out the **[Getting Started Guide](/docs/gettingStartedMod.md)**
+
+Before you can start using your bot on reddit there are a few steps you must take:
+
+* Create your bot account IE the reddit account that will be the "bot"
+* Create a Reddit application
+* Authenticate your bot account with the application
+
+At the end of this process you will have this info:
+
+* clientId
+* clientSecret
+* refreshToken
+* accessToken
+
+**Note:** If you already have this information you can skip this guide **but make sure your redirect uri is correct if you plan on using the web interface.**
+
+# Table Of Contents
+
+* [Creating an Application](#create-application)
+* [Authenticate Your Bot](#authenticate-your-bot-account)
+  * [Using RCB OAuth Helper](#rcb-oauth-helper-recommended)
+  * [Using Aardvark OAuth Helper](#aardvark-oauth-helper)
+* [Provide Credentials to RCB](#provide-credentials-to-rcb)
+
+# Create Application
+
+Visit [your reddit preferences](https://www.reddit.com/prefs/apps) and at the bottom of the page go through the **create an(other) app** process.
+* Give it a **name**
+* Choose **web app**
+* If you know what you will use for **redirect uri** go ahead and use it, otherwise use **http://localhost:8085** for now
+
+Click **create app**.
+
+Then write down your **Client ID, Client Secret, and redirect uri** somewhere (or keep this webpage open)
+
+# Authenticate Your Bot Account
+
+There are **two ways** you can authenticate your bot account. It is recommended to use the RCB oauth helper.
+
+## RCB OAuth Helper (Recommended)
+
+This method will use RCB's built in oauth flow. It is recommended because it will ensure your bot is authenticated with the correct oauth permissions.
+
+### Start RCB with Client ID/Secret
+
+Start the application while providing the **Client ID** and **Client Secret** you received. Refer to the [operator config guide](/docs/operatorConfiguration.md) if you need help with this.
+
+Examples:
+
+* CLI - `node src/index.js --clientId=myId --clientSecret=mySecret`
+* Docker - `docker run -e "CLIENT_ID=myId" -e "CLIENT_SECRET=mySecret" foxxmd/reddit-context-bot`
+
+Then open the RCB web interface (default is [http://localhost:8085](http://localhost:8085))
+
+Follow the directions in the helper to finish authenticating your bot and get your credentials (Access Token and Refresh Token)
+
+## Aardvark OAuth Helper
+
+This method should only be used if you cannot use the [RCB OAuth Helper method](#rcb-oauth-helper-recommended) because you cannot access the RCB web interface.
+
+* Visit [https://not-an-aardvark.github.io/reddit-oauth-helper/](https://not-an-aardvark.github.io/reddit-oauth-helper/) and follow the instructions given.  
+  * **Note:** You will need to update your **redirect uri.**
+* Input your **Client ID** and **Client Secret** in the text boxes with those names.
+* Choose scopes. **It is very important you check everything on this list or RCB may not work correctly**
+    * edit
+    * flair
+    * history
+    * identity
+    * modcontributors
+    * modflair
+    * modposts
+    * modself
+    * mysubreddits
+    * read
+    * report
+    * submit
+    * wikiread
+    * wikiedit (if you are using Toolbox User Notes)
+* Click **Generate tokens**, you will get a popup asking you to approve access (or login) -- **the account you approve access with is the account that Bot will control.**
+* After approving an **Access Token** and **Refresh Token** will be shown at the bottom of the page. Save these to use with RCB.
+
+# Provide Credentials to RCB
+
+At the end of the last step you chose you should now have this information saved somewhere:
+
+* clientId
+* clientSecret
+* refreshToken
+* accessToken
+
+This is all the information you need to run your bot with RCB.
+
+Using these credentials follow the [operator config guide](/docs/operatorConfiguration.md) to finish setting up your RCB instance.