Obtaining Ads Account credentials

Overview

There are two methods you can use to make Ads API requests for an advertiser’s account: making requests on behalf of an Advertiser (recommended) and making requests using your account that has been granted access to an Advertiser's account, e.g. an Agency supporting multiple accounts. This document is a brief overview of the differences between these options and should be used in conjunction with our other resources, such as the multi-user login FAQ

As described in Authorizing a request, all requests to the Ads API require Authorization headers using OAuth 1.0a with an access token obtained via 3-legged OAuth flow. Your application will need to implement a web-based OAuth flow to obtain access tokens. Ads API developers should never request that our Twitter advertisers share their login credentials.

By default, each Twitter developer application contains a static access token that can be used to make Ads API requests for the account that owns the application. These credentials are ideal for single-account use cases without requiring a 3-legged or PIN-based OAuth flow. If you aren't accessing another Twitter Ads Account, use these single-user credentials instead of the following steps.

Levels of access

Each user that has access to an Ads Account will have a specific account-level permission: Account administrator, Ad manager, Campaign analyst, Organic analyst, and Creative Manager; see business.twitter.com for the latest documentation for account-level permissions. Applications should retrieve the permissions for the currently authenticated user via the Authenticated User Access API endpoint to determine which API endpoints and Ads features they can access.

Methods of obtaining access tokens

1. Obtain an advertiser's (User) access token

There are two methods of obtaining an advertiser’s access token. The most common method is via a 3-legged OAuth flow directly from within your web UI. Applications that do not have a publicly accessible UI exposed to advertisers can implement an PIN-based Oauth process. After the user completes the 3-legged flow, your application will have credentials to make request for their Ads account via the API.

Obtaining user credentials via OAuth flow is the method we highly recommend for the majority of Ads API developers to gain access to an advertiser account. It allows you to call the API on behalf of a user and take actions as that user. These tokens do not expire but can be revoked by the user at any time.

2. Obtain your (Developer) access token

This option requires the advertiser to grant your @username (or @usernames) access to their Twitter Ads account via the Twitter UI at ads.twitter.com. Access tokens obtained through the 3-legged OAuth flow for your account will be able to access the advertiser's Twitter Ads account.

This allows you to call the API using the OAuth tokens of your own @username rather than the advertiser’s OAuth tokens. The key distinction on this option is that you may only create Promoted-Only Tweets if the Tweet delegation/composer permission has been granted to your @username.

To gain access to create Promoted-Only Tweets on behalf of the FULL promotable user on the account, you must also be granted access to create Tweets in this flow. That will enable access via the TWEET_COMPOSER permission on the GET accounts/:account_id/authenticated_user_access endpoint.

Differences between these methods

  Advertiser (User) OAuth Token
(Developer) OAuth Token
 (@username added to separate account)
Access Ads Account
Create Tweets on Behalf of User ✔*
Manage Campaigns
Access Analytics
Create Cards on Behalf of User
Developer ability to Access
via Twitter Ads UI
 
Rate Limits Distinct per Advertiser Distinct per Advertiser Account

* see Obtain your (Developer) access token section above for details.

Sample Use-Case

Advertiser's access token via OAuth 3-legged web flow

The standard flow is web-based and uses the 3-legged authorization OAuth flow. The screen shots outlined here are part of a sample that you can view the source of at https://github.com/twitterdev/twauth-web.

At some point in your application, you will want to redirect to Twitter in order to authorize your application image0 When you redirect to Twitter with the request token, the user will be prompted to authorize your application image1 Upon authorizing your application, the user will be redirected to the callback URL provided when you generated the request token. You will use this to obtain the permanent access token for this user and store it locallyimage2