Setting Up the API

There are several steps we need to perform before we can start using the Reddit API.

Register the app

The first thing we have to do is register our client with Reddit. To do this first log into your Reddit account. Since your account will be tied to this app you may instead wish to create an account for the bot we'll be writing instead. Once you're logged in go here and fill out the form to register your app. Most of the information presented is for developers making a web app or mobile app. Since we're building a bot we only need it to run on one machine, like a server. Fill our your form like so:

Name: The name of your application (use something unique).
App type: There are only three options presented as radio buttons. Select "script".
Description: Your app's description. You can leave this blank.
About URL: Leave this blank.
Redirect URI: The URI that the client will redirect to when authenticating the user. Since local scripts don't need to authenticate users you can leave this blank.

Once you’ve created your application you’ll be redirected to a page that summarizes the app’s information. There are two new fields we’re interested in, the client ID and the secret key. The client ID is in the top left corner under your app’s name. The secret key is the string following the label “secret”. Save both of these for later, you’ll need them to authenticate with later.

Authentication

Reddit's authentication documentation can be found here. However, there are several methods to authenticate depending on what you want to do and they are not simple. In fact, the authentication methods are API calls themselves, and they are by far the hardest part of using the Reddit API. There aren't many good resources out there on getting past this hurdle, so I'll walk through the steps.

For our purposes (making a local script) there are two relevant options depending on what we want to do. We can either log in as ourselves and have access to all OAuth calls that require a user to be logged in, or just authenticate the app without logging in. Both will give you access to OAuth-required API calls, but only the log in option will allow you to access API calls that perform user-specific options (e.g., posting comments, viewing account details). To get full access to the API we'll authenticate with our account.

Using Node and the requests module, the code to authenticate will look like:

var request = require("request");

var clientid = YOUR_CLIENT_ID;
var secret = YOUR_CLIENT_SECRET;
var options = {
                url: "https://www.reddit.com/api/v1/access_token",
                method: 'POST',
                contentType: 'application/x-www-form-urlencoded',
                headers: {
                    'User-Agent': YOUR_USER_AGENT
                },
                auth: {
                    'username': clientid,
                    'password': secret
                },
                body: 'grant_type=password&username=YOUR_USERNAME&password=YOUR_PASSWORD',
             };

request(options, function(err, res, body) {
    var json = JSON.parse(body);
    var token = json['access_token'];
    getThreads(token);
});

Let’s go through this line by line. The URL field specifies which API endpoint we need to hit, in this case

First we set variables for our client ID and secret that we obtained earlier when we registered out app. It’s not necessary to do this, but it makes it easier to hide or change later. Remember, we don’t want our client secret getting out!

Next, we configure all the options we’ll need to make our request. The URL field specifies which API endpoint we need to hit, in this case "https://www.reddit.com/api/v1/access_token". The method field specifies what kind of request to make. The Reddit API says we have to make a POST request. Content-Type needs to be set to “application/x-www-form-urlencoded” according to the API. In the header field we’ll specify our user-agent. As stated earlier, this can be any unique string you want.

The “auth” option tells the request module to use HTTP basic authentication. For the Reddit API, the “username” is your client_id and the “password” is your client_secret. Finally, we set the content of our POST request with the “body” option. This is where you can choose between application or user authentication. If you wish to use application authentication then all you need to put is “grant_type=client_credentials”. If you wish to use user authentication, you’ll need to include the user’s username and password, and set grant_type to “password”. So the body for this would look like

'grant_type=password&username=YOUR_USERNAME&password=YOUR_PASSWORD'

To actually send the request and process the response we call the request object and provide our options object as the first argument. The second argument is a callback that takes the response, error, and body of the response. We only care about the body which will be returned to us in JSON format.

{
    "access_token": The access token you'll need to access the rest of the API,
    "token_type": "bearer",
    "expires_in": The amount of time until the authentication expires,
    "scope": What parts of the API you have access to
}

Save the access token and we’re done! Now we can access the OAuth-only API calls. Note that the access token expires after one hour, so you’ll need to refresh it if your app’s session goes any longer than that. This is accomplished by including the string

grant_type=refresh_token&refresh_token=TOKEN

In your POST data. You also need to include “duration=permanent” in your original authorization request.