Get Started with OAuth 2.0

OAuth is a popular standard that allows AdRoll 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 AdRoll 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);
  }
));