Authentication

The Roku Ads API uses OAuth 2.0 to authenticate users and provide access to ad accounts. This process consists of three steps:

Set up an app

Obtain access

Generate an access token

Set up an app

To create a developer app you need to have an admin role for a Roku Ads Manager organization. The app you create belongs to your organization and can't be moved to another organization later. You can use a single developer app to obtain access to multiple advertisers’ ad accounts.

1. Sign in to Ads Manager.
2. Open Organization page, by clicking the user profile icon in the top right corner and selecting Organization.
3. On the Ads API tab, click Add developer app.
4. Enter your developer app details:
   • App name
   • App logo
   • Company website
   • Redirect URI - Where your user is redirected upon authentication.
5. Click Add app.

   🚧

   Once you create your app it's locked to the organization for which it was created and can't be moved to another organization.

6. Your client secret is displayed only this one time, save it now in a secure location. You need to provide it later to obtain your access token.
7. Copy the following from the Ads API tab, you'll need to provide them later to obtain access:
   • Client ID
   • Authorization URL

Obtain access

If you're working with the Ads API as a partner to an agency or advertiser, they have to complete the steps of the "user" in this process. If you're an agency or advertiser who wants direct access to the Ads API, you can follow this process as the "user" and can grant yourself access.

1. Direct the user to the authorization URL obtained at the end of the Set up an app process, above. They are presented with a request to give you access to the relevant ad accounts with specified roles.
2. Once access is granted, the user is redirected to the redirect URI that was provided in the Set up an app process, above.
3. Save the code appended to the redirect URI. You need to provide this code later to obtain your access token.

Generate an access token

First-time authentication

To generate an access token for the first time:

Make an Obtain or refresh an access token call and include the following request body parameters:

• client_id - your app's client identifier, obtained when you set up an app.
• client_secret - your app's client secret for authentication, obtained when you set up an app.
• grant_type - for first-time authentication grant_type should be set to authorization_code.
• code - the authorization code required for a first-time authentication (when grant_type is set to authorization_code), obtained at the end of the redirect UI in the approve access process.
• redirect_uri - the redirect URI used in the authorization request, provided when you set up an app.

A successful call returns the created access_token with a token_type value, typically Bearer, an expires_in value which indicates the lifetime of the access token in seconds, and a refresh_token which can be used to refresh your access token when you need a new one.

Include your access_token in all of your API calls.

Refresh your access token

Access tokens expire in 24 hours. If your authentication call returns a 401 error about token expiration, use your refresh token to obtain a new access token.

Make an Obtain or refresh an access token call and include the following request body parameters:

• client_secret - your app's client identifier, obtained when you set up an app.
• grant_type - to refresh your access token, grant_type should be set to refresh_token.
• refresh_token - the token required to refresh your access token, obtained when you complete your first-time authentication.

A successful call returns the created access_token with a token_type value, typically Bearer, and an expires_in value which indicates the lifetime of the access token in seconds.

Include your access_token in all of your API calls.