There are two different types of accounts involved in using the Ads API: advertising accounts and Twitter user accounts. Throughout Ads API documentation, the term “account” usually refers to the advertising account.
- Advertising accounts are registered on ads.twitter.com and identified in the API by account_id. Advertising accounts link directly to funding sources and leverage content from one or more Twitter user accounts as ‘promotable users’. Each advertising account can grant permission to one or more Twitter user accounts. The advertising account, or “current account,” is represented in nearly every URL executed as an in-line :account_id parameter.
- Twitter user accounts (such as @AdsAPI) are identified by user_id in the Ads API. One or more of these accounts can be associated with an advertising account. The authenticated Twitter user account making requests on the API is referred to as the ‘current user.’ A listing of advertising accounts that the current user has access to can be found with GET accounts. ‘Promotable users’ are Twitter handles that can be promoted by a specific advertising account. For more details about this, see Obtaining Ads Account Access.
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)
- 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.
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.
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.
|Advertiser (User) OAuth Token||
(@username added to separate account)
|Access Ads Account||✔||✔|
|Create Tweets on Behalf of User||✔||✔*|
|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.
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 When you redirect to Twitter with the request token, the user will be prompted to authorize your application 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 locally