Platform: Managing Reddit Authorizations

Reddit API access is managed by the redball platform, rather than each bot having to handle it independently. This allows you to authorize your bot account once and use that authorization for each bot.

To set up a Reddit authorization, first you have to create an app on the Reddit developer website.

• Log in to Reddit with the account you want your bot to run as
• Go to https://www.reddit.com/prefs/apps
• Click the link/button to create an app
• Give your app a name, redball for example
• Select web app, enter a description and about url if you want
• For redirect uri, it is very important that you enter the same value as the HTTP Root on the System Config page, suffixed with /authorize. This should be the URL you use to access the web interface, e.g. http://localhost:8087/authorize, or if you use a reverse proxy it might be something like https://redball.mydomain.com/authorize. If the redirect uri on your Reddit app does not match the HTTP Root setting plus /authorize, you will receive an invalid grant error when attempting to complete the authorization.
• Submit the form to create your app

Once your app is created, you will need to copy the client id and secret into a new Reddit Authorization in the redball System Config page.

The client id is under your app's name at the top left of the app display.

Click the edit link on your app to see the secret.

Select the scopes required for your bot, or just select all of them if you don't know which are required. You can always come back to this page, edit the auth to change which scopes are allowed, and re-authorize if you miss one.

• edit: 'Edit and delete my comments and submissions.
• identity: Access my reddit username and signup date.
• modconfig: Manage the configuration, sidebar, and CSS of subreddits I moderate.
• modflair: Manage and assign flair in subreddits I moderate.
• modlog: Access the moderation log in subreddits I moderate.
• modposts: Approve, remove, mark nsfw, and distinguish content in subreddits I moderate.
• mysubreddits: Access the list of subreddits I moderate, contribute to, and subscribe to.
• privatemessages: Access my inbox and send private messages to other users.
• read: Access posts, listings and comments through my account.
• submit: Submit links and comments from my account.
• subscribe: Manage my subreddit subscriptions.
• vote: Submit and change my votes on comments and submissions.

After you save the Reddit Auth in redball System Config, click the authorize button to open Reddit and allow the app access to your account (make sure you're logged in as your bot account).

If your browser does not open automatically (this will happen if you are running redball on a remote server), ensure you are logged in to Reddit as your bot user, and then click the link in the information bar at the top of the screen to open the authorization URL.

After you authorize the app to access your Reddit account, you should be redirected to redball with a code in the address bar of your browser. The code should be processed by redball automatically, and you should see a refresh token listed under the Reddit Auth you just authorized. If you see an error instead, your redirect uri likely did not match. See above and try again.

Allowing Others to Authorize their Reddit Account

In the event you do not have the password for the Reddit account you want to authorize, you can provide the authorization URL from the information bar to the account owner and ask them to log in as the bot account and click the link. However, redball must be accessible by the user authorizing the account at the redirect uri you have configured. If you do not have redball accessible from the Internet, this will not be possible. The user will instead need to either provide you with the account password, or use the standalone authorization tool and provide you with the refresh token which you can add to the authorization record in redball's System Config.

Standalone Reddit Authorization

If your instance of redball is not accessible from the Internet, and you need a bot account owner to authorize redball for you, the account owner can use the reddit_auth_standalone.py script included with redball. This requires Python 3 with the praw module installed.

Provide the following information to the bot account owner:

• Reddit App ID
• Reddit App Secret
• Reddit App Redirect URI (the value from your app even though it won't be accessible for the account owner)
• List of scopes you want to authorize, in json format (e.g. ["identity", "submit", "edit", "read", "modposts", "privatemessages", "flair", "modflair"])

The account owner can run python3 reddit_auth_standalone.py and follow the prompts to generate a refresh token for you.

Refresh Token Management

As of February 2021, the Reddit API started providing a new refresh token as part of the authorization process. Starting with v1.2, redball has support for rotating refresh tokens, and will only use each refresh token once. The Reddit API is expected to start expiring refresh tokens after a single use in Q2 2021. See this post for more information about the change being made on the Reddit side.

Bot developers should note that the redball platform (as of v1.2) will no longer provide a refresh token directly to an instance of a bot. Instead, the bot should pass the bot instance's reddit_auth_token_manager object to praw, as shown below. The token manager will manage updates to the refresh token stored in the Reddit authorization on redball's System Configuration page. Refresh token management will be logged in redball.log (search for redeeming and storing).

Also note the use of a lock stored in redball.REDDIT_AUTH_LOCKS, with the bot's redditAuth id (cast to a string) as the dict key. This ensures only one bot can redeem the refresh token at a time, in case there are multiple bots using the same Reddit authorization (this will be important on startup, once Reddit starts expiring refresh tokens after a single use).

Keep in mind an actual call to the Reddit API is not made until an action is performed, so be sure to do that while still holding the Reddit auth lock. In the example below, a call to praw's user.me() method ensures a call to the Reddit API is made. Note further that if the identity scope is not authorized, calls to user.me() will fail--this may or may not be a problem for your bot, depending on required scopes.

with redball.REDDIT_AUTH_LOCKS[str(self.bot.redditAuth)]:
    self.reddit = praw.Reddit(
        client_id=self.settings["Reddit Auth"]["reddit_clientId"],
        client_secret=self.settings["Reddit Auth"]["reddit_clientSecret"],
        token_manager=self.bot.reddit_auth_token_manager,
        user_agent="redball Bot Example - https://github.com/toddrob99/redball/ - r/{}".format(
            self.settings["Reddit"].get("SUBREDDIT", "")
        ),
    )
    self.log.info("Reddit authorized user: {}".format(self.reddit.user.me()))

All of the standard bots have been updated with this new logic.