Authenticate Your Developer Application

You can set up your developer application to gain access to the Reddit API, letting you develop nifty applications and integrations that seamlessly interact with Reddit's ads platform.

Before you begin, you should have:

• A Reddit Ads account.
• A developer application. You’ll need its app ID and secret.
• Access to a terminal application.

1. Authorize your application

Go to your business’s developer applications and find your application’s app ID. Replace the values in the following link and navigate to it:

https://www.reddit.com/api/v1/authorize?client_id={{App ID}}&response_type=code&state={{Random String}}&redirect_uri={{Redirect URL}}&duration={{Duration}}&scope={{Scope}}

• {{App ID}}: The ID of your dev app
• {{Random String}}: This can be set to any string with no spaces or special characters, like the name of your dev app. This is used to detect cross-site request forgeries (CSRF). You can also set a signature for additional security.
• {{Redirect URL}}: The redirect URL you set for your dev app.
  Don’t change redirect_uri to redirect_url. This parameter must be used so that the application can correctly route mobile and web application redirects.

• {{Duration}}: The time limit that this access token will expire. You probably want to set this to permanent, but you can set it to temporary to make the access code valid for only one hour.
  If you set this to temporary, you won’t be able to refresh this option.

• {{Scope}}: A comma-separated list of the actions performable with the access token.
  If you’d like your token to access everything in the Reddit Ads API, you can set this to adsread,adsconversions,history,adsedit,read. 

Scope	Description
adsconversions	Post conversion events by enabling access to the Conversions endpoint
adsedit	Edit ads data
adsread	Read advertising data for your account
history	Access submission history
read	Read posts and comments for your Reddit user account

Example: Get link based on credentials

Field	Value
App ID	DnvSjQYG9t13lWWOndNqOg
Redirect URL	https://www.reddit.com/prefs/apps
Scope	Post conversion events with the Conversions API (CAPI)
Link	https://www.reddit.com/api/v1/authorize?client_id=DnvSjQYG9t13lWWOndNqOg&response_type=code&state=sgtm-capi&redirect_uri=https://www.reddit.com/prefs/apps&duration=permanent&scope=adsconversions

Check that the username listed matches the account you want to authorize the app. If the username is correct, select Allow.

If an unexpected username is displayed, you’re in an active Reddit session. To fix this, log out of your account, log into the correct account, then revisit the URL.

You will be sent to the redirect URL that you provided earlier. The URL in your address bar will have two query parameters: the state and the code. Copy and record the code value and remove the #_ characters at the end of the value, if any.

This code should be used within the next ten minutes and only once per authorization.

Example: Find code value from redirect URL

Redirect URL	Code value
https://notarealbrand.myshopify.com/oauth/callback?state=my-state&code=Ve49meZ9oh3lZFY35CEizm3jTsfJeA#_	Ve49meZ9oh3lZFY35CEizm3jTsfJeA

2. Get your access token from the Reddit API

Open a terminal window and execute the following cURL command with your noted values:

curl -X POST https://www.reddit.com/api/v1/access_token \
     -H 'content-type: application/x-www-form-urlencoded' \
     -A '{{Name}}' \
     -u '{{App ID}}:{{Secret}}' \
     -d 'grant_type=authorization_code&code={{Redirect Code}}&redirect_uri={{Redirect URL}}'

Example: Get access token

Field	Value
Name	SGTM-CAPI
App ID	DnvSjQYG9t13lWWOndNqOg
Secret	Ucr7PXIWe_OK_vAsrE0J3kvDJ0faww
Redirect Code	QGRMgx3l54x0s8NT_WdcuSt_Adi9nA
Redirect URL	https://www.reddit.com/prefs/apps
Code	curl -X POST https://www.reddit.com/api/v1/access_token \ -H 'content-type: application/x-www-form-urlencoded' \ -A 'SGTM-CAPI' \ -u 'DnvSjQYG9t13lWWOndNqOg:Ucr7PXIWe_OK_vAsrE0J3kvDJ0faww' \ -d 'grant_type=authorization_code&code=QGRMgx3l54x0s8NT_WdcuSt_Adi9nA&redirect_uri=https://www.reddit.com/prefs/apps'

If successful, you will receive a response that looks like this:

{
    "access_token": {{Access token}},
    "token_type": "bearer",
    "expires_in": {{Expiration time in Unix epoch}},
    "refresh_token": {{Refresh token}},
    "scope": {{Scope string}}
}

Record the value for access_token and refresh_token. You’ll use access_token to access the Reddit Ads API for either one hour (3600) or one day (86400), whichever is listed for the value for expires_in.

3. (Optional) Refresh your access token

You can use an active access token to maintain continuous access to the API without requiring re-authentication. 

To refresh your token, open a terminal window and execute the following cURL command with your noted values:

curl -X POST https://www.reddit.com/api/v1/access_token \
     -A '{{Name}}' \
     -u '{{App ID}}:{{Secret}}' \
     -d 'grant_type=refresh_token&refresh_token={{Refresh token}}'

Example: Refresh token

Field	Value
Name	SGTM-CAPI
App ID	kmY1CRszT3obFwYeU3uuEw
Secret	rTBVO3UirF-fcwvlMNellSxqkd3wSQ
Refresh Token	90773738700875-TEhYsiu7TO6A6PIWuiweSH_PBW96lw
Code	curl -X POST https://www.reddit.com/api/v1/access_token \ -A 'SGTM-CAPI' \ -u 'kmY1CRszT3obFwYeU3uuEw:rTBVO3UirF-fcwvlMNellSxqkd3wSQ' \ -d 'grant_type=refresh_token refresh_token=90773738700875-TEhYsiu7TO6A6PIWuiweSH_PBW96lw'

If successful, you will receive a response that looks like this:

{
    "access_token": {{Access token}},
    "token_type": "bearer",
    "expires_in": {{Expiration time in Unix epoch}},
    "refresh_token": {{Refresh token}},
    "scope": {{Scope string}}
}

Record the value for access_token and refresh_token. You’ll use access_token to access the Reddit Ads API for either one hour (3600) or one day (86400), whichever is listed for the value for expires_in.