OAuth2
OAuth2 support allows you to use Reddit to authenticate on non-Reddit websites.
First you need an application id and secret so Reddit knows your application. You get this information by going to https://ssl.reddit.com/prefs/apps and clicking "are you a developer? create an app..."
Most of the fields don't matter much, just give it a reasonable name and description. The most important thing is the redirect uri, this should be a URL where you plan to host the script that users are redirected to after allowing access.
The part underlined in red is your consumer key (also called the client id), and the part in blue is your consumer secret (also called the client secret. You should never share this.) Hold on to them because you'll need them to write your app later.
This is information that you'll need in addition to your consumer key and secret to set up an OAuth app:
- Authorization url:
https://ssl.reddit.com/api/v1/authorize(Also known as the authorization endpoint) - Access token url:
https://ssl.reddit.com/api/v1/access_token(Also known as the token endpoint)
The authorization url is where you send a user's browser, so they can grant limited access to their account to your application. If the user grants access, they are redirected to your redirect uri with a code. Your app then makes a call to the access token url, using the code it received, to obtain the access token. Note that the request to the access token url must use Basic HTTP authentication with the consumer key as the username and the consumer secret as the password. If you do not provide the authentication header, or the information is incorrect, then you will receive an HTTP 401 Unauthorized response.
Once your app receives an access token, it can use it on the https://oauth.reddit.com domain to make API calls as that user (until the token expires or is revoked by the user). Note the different domains involved:
- https://ssl.reddit.com - for authorization and access_token fetching
- https://oauth.reddit.com - for API calls with an access token
In addition to the standard authorization parameters (response_type, client, redirect_uri), you may specify these additional parameters that may be important to the development and usage of your application:
- scope - In order to use oauth approved calls on this page, you must specify the scope from which the call originates from. For example, if you wish to use the '/api/v1/me' call, you must specify the identity scope. If you wish to use '/api/approve' and '/api/remove', specify the modposts scope. If you need to use more than one scope, they should be specified in a comma delimited manner.
- state - You can pass a value into the authorization page that will be included in the redirect back to you if the user grants access. This is useful for preventing cross-site request forgery (CSRF). By choosing (and remembering) a sufficiently random value, you can ensure that the request that comes back to your site was initiated by visiting the authorization URL you generated.
- duration - Duration is useful if you require a permanent token. By default if duration is not specified, temporary will be chosen. The alternative is to specify permanent and a permanent token will be issued. The user will also be aware you are requesting permanent access. Learn more about refreshing that token here.
Here is example code on using OAuth in various languages:
Right now not quite all of the Reddit API is available to OAuth clients, furthermore OAuth tokens only last a short amount of time. This is slated to change in the future, but for the meantime this means OAuth is not the ideal solution for things like mobile Reddit apps (permanent tokens are now available).
You can look at the Reddit API documentation page to see if a particular API has oauth support.