Making Authenticated API Requests

Overview

Accessing the Twitter Ads API endpoints requires your application to send authenticated web requests securely using TLS to https://ads-api.twitter.com.

The following sections will provide an overview of making authenticated API requests, setting up Twurl to interact with the API, and extending your application to support OAuth 1.0a and make requests against your Ads account.

Requirements

Before making authenticated requests to the Twitter Ads API, you will need:

Using Access Tokens

The Twitter Ads API uses signed HTTPS requests to validate an application’s identity and also obtain the permissions granted to the end-user that the application is making API request on behalf of, represented by the user's access token. All HTTP calls to the Ads API must include an Authorization request header (using OAuth 1.0a) over the HTTPS protocol.

You will need to add support to generate OAuth 1.0a Authorization request headers to your application to integrate with the Twitter Ads API. However, due to the complexity of generating signed requests, we strongly recommended that partners use an existing library that either supports the Twitter API or implements OAuth 1.0a request handling - here is a list of recommended OAuth libraries and authentication code samples.

Note we can assist partners that encounter authentication errors when using a known library but cannot support custom OAuth implementations.

Making your first API request with Twurl

Twitter helps maintain a command-line tool, Twurl, that supports OAuth 1.0a authorization headers as an alternative to cURL. Twurl provides a simple way of making authenticated API requests and exploring the Ads API before adding authentication to your application.

After installing and authorizing Twurl, you can quickly generate access tokens and make authenticated requests to the Ads API.

   twurl -H "ads-api.twitter.com" "/5/accounts/"

Take some time to get familiar with Twurl and the API by following this step-by-step tutorial for creating a campaign through the API.

Testing with Postman

For those who are not familiar with a command-line tool, we also provide a Postman collection for the Twitter Ads API endpoints.

Postman is one of the most popular API development tools that exist in the industry nowadays. It’s an HTTP client that has a great user interface that lets you make a complex API request easier and increases productivity.

To install Postman and start using the Ads API Postman collection, please see our set up guide.

Extending your application to make authenticated requests

After getting familiar with making requests to the Ads API using Twurl, it is time to add support to create OAuth 1.0a authentication headers to your application.

OAuth 1.0a authentication headers include information that verifies both the application’s and user's identity as well as prevents tampering with the request. Your application will need to create a new Authorization header for each API request. Many languages have open source libraries that support creating this authorization header to make API requests to Twitter.

Here are some examples using C#, PHP, Ruby, and Python - code samples.

Custom Implementation

There are some scenarios that require implementing OAuth 1.0a authentication without the support of an open-source library. Authorizing a request provides detailed instructions for implementing support for creating the Authorization header. We strongly recommend using a community-supported library.

General outline:

  1. Collect 7 key/value pairs for the header - starting with oauth_
  2. Generate an OAuth 1.0a HMAC-SHA1 signature using those key/value pairs
  3. Build the Authorization header using the above values

Next Steps

After adding support for the Authorization header, you should have a simple application that can successfully make authenticated requests to the Twitter ads API.

To access another user’s Twitter Ads account, your application will need to obtain access tokens via the 3-legged OAuth flow.

If your application will only access your Twitter Ads account, proceed to the Upload Video and Promote Tweet Guide to upload Creatives that can be used in a campaign.

Resources

Development tools

  • Twurl -  command-line tool for interacting with the Twitter API
  • Postman - development tool for manually inspecting 3rd Party APIs

 

Twitter libraries that support the Ads API

  • Python - Twitter supported
  • Ruby - Twitter supported
  • Java - Twitter recommended

Request Header Authorization libraries that support OAuth 1.0a