Get Started with OAuth 2.0

OAuth is a popular standard that allows users to give account access to third party developers without having to share their password. For a general overview of OAuth 2.0, checkout the official getting started guides.

AdRoll’s OAuth implementation conforms to RFC 6749 and uses Bearer Tokens (RFC 6750).

Endpoints

Authorization

https://services.adroll.com/auth/authorize

Token

https://services.adroll.com/auth/token

Supported Grant Types

Authorization Code Grant (aka three-legged)

Most commonly used grant type.

Implicit Grant

Used when your client secret cannot be kept secret (such as single-page web applications)

Resource Owner Password Credentials Grant

Used when your cannot use web browser redirection. Use only when the previous two grant types doesn’t work for you.

Supported Scopes

That this time, we only support a single scope. We plan to implement fine-grained scopes in the future.

all

Gives you access to all resources. This is the default if no scope is specified.

Token Lifetime

Access Tokens

Expire 24 hours after they are issued for all supported grant types

Refresh Tokens

Expire a year after they are issued and after they are used. You’ll receive a new refresh token along with your new access token.

Making Authenticated Requests

Once you’ve received an access token, you can include it in your API calls using any of the methods defined in the Bearer Tokens specification (RFC 6750).

Authorization Request Header

You can use the Authorization header by specifying the Bearer scheme like this:

Authorization: Bearer {ACCESS_TOKEN}

Form-Encoded Body Parameter

When making requests with the application/x-www-form-urlencoded content-type, you can specify the access_token as another parameter. For example:

access_token={ACCESS_TOKEN}&advertisable_eid=1C5489F116A0DA38618850

URL Query Parameter

You can include your access token in the query in the component of the URL. For example:

https://services.adroll.com/api/v1/organization/get?access_token={ACCESS_TOKEN}

Your First API Call

There are many OAuth libraries that take the effort out of managing OAuth tokens. You should be able to plug the authorization and token URLs into your favorite OAuth 2.0 library.

Python

For Python, you can use the requests-oauthlib library. You can update the authorization_base_url and token_url variables in the web app example.

Node.js

For Node.js you can use the Passport middleware with the passport-oauth2 strategy:

passport.use(new OAuth2Strategy({
    authorizationURL: 'https://services.adroll.com/auth/authorize',
    tokenURL: 'https://services.adroll.com/auth/token',
    clientID: 'YOUR CLIENT ID',
    clientSecret: 'YOUR CLIENT SECRET',
    callbackURL: "http://example.com/callback"
  },
  function(accessToken, refreshToken, profile, cb) {
    console.log(accessToken, refreshToken, profile);
    // TODO: Save accessToken and refreshToken for later use
    return cb(null, profile);
  }
));

Outline for a server to server integration

  1. Create your developer account.

  2. Once logged in, go to My Apps and click on Add New App. Once you’ve created your application, click on the application to get your client id and client secret.

  3. Your initial auth code request should look like below, replacing the [CLIENT_ID] and [REDIRECT_URL] placeholders with your appropriate values that you can copy from registered app:

https://services.adroll.com/auth/authorize?response_type=code&client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URL]

  1. Once you have replaced the placeholders, you can visit this URL in your web browser, it will redirect you to OAuth authorization page. It requires you to be signed into the dashboard, and you must click on the Authorize button to continue.

  2. After you have authorized your NextRoll account and granted access to your app, you will be redirected to the [REDIRECT_URL] that you provided while registering the app and you will be provided an authorization access code in the query parameter of redirect.

https://www.your-redirect-url.com/?code=AIWUVOQA&scope=all

  1. Copy this temporary auth code, and you can use a REST client like POSTMan to test getting access tokens from the below endpoint.

POST https://services.adroll.com/auth/token

grant_type=authorization_code&
code=AUTH_CODE_HERE&
redirect_uri=REDIRECT_URI&
client_id=CLIENT_ID&
client_secret=CLIENT_SECRET

  1. For the subsequent requests to renew access token after it expires in 24 hours, you should store and use your previous refresh token that you received along with the access token. The response will be a new access token along with a new refresh token that you can use next time.

POST https://services.adroll.com/auth/token

grant_type=refresh_token&
refresh_token=REFRESH_TOKEN_HERE&
client_id=CLIENT_ID&
client_secret=CLIENT_SECRET