Introduction

This document details generating access tokens that can be used by your web clients to make secure, direct calls to Foursquare Targeting’s APIs. Using tokens enables you to avoid proxying API calls through your own servers and is a required piece of implementing an embeddable UI workflow.

Requirements

The basic requirements to implement tokens to access Foursquare Targeting are:

• A server in your control that can authenticate your clients against your own user DB
• A Foursquare Targeting API key
• The ability for your server to make an outbound API call to Foursquare Targeting
• The ability for your server to forward the results of an API call from Foursquare Targeting to your clients

The diagram below details the basic authentication flow:

As shown in the diagram above, the basic steps are:

1. Your user attempts to login from one of your clients by sending login credentials to your server.
2. Assuming the user has acceptable credentials, your server will either:

• Return the most recent Foursquare Targeting authentication token it has for the user (assuming that it hasn’t passed its expiration date).¹
• Request a new token from Foursquare Targeting on behalf of that user.²

3. In the event a token was requested, Foursquare Targeting will return the token to your server.
4. Your server in turn will return the access token to the client.
5. Your client will use the token to make a request to Foursquare Targeting.
6. Foursquare Targeting will determine if the token is valid, and what permissions it should have.
7. As appropriate, Foursquare Targeting will return data to the client.

📘

Note:

Until your client’s Foursquare Targeting token has expired, your client does not need to re-request tokens to make calls to Foursquare Targeting.

There is no harm in asking for a token redundantly. Foursquare Targeting will consistently return the same token is for that user.

If this is the first time the user has requested access to Foursquare Targeting, all necessary configuration on Foursquare Targeting’s side will be performed immediately, in order to respond to your server’s request in a timely manner. I.e., each user’s Foursquare Targeting credentials are generated quickly but lazily.

Getting an API Key

If you haven't already, contact Foursquare Targeting to register an account. Once you have an account, ask Foursquare Targeting to create a new Server App key for you.

1. Go to the Foursquare Targeting API key manager at https://accounts.targeting.foursquare.com/keys.
2. View your Server App key and click the Modify link.

3. In the Security and Permissions section, enter the IP address of your server. This helps prevent use of your API key to generate tokens from unauthorized domains, if it were to be compromised.
4. Hit Save.

Getting Tokens

Tokens are generated using an https request to Foursquare Targeting’s V4 API. Authentication of your token API call is performed simply by supplying your API key to the KEY parameter (all CAPS) to the /token/user endpoint. Along with your API key, the following parameters are required (unless you provide a user Id, as detailed later):

• email (User email address.)
• first_name (first name of user. must not be blank or all white space.)
• last_name (last name of user. must not be blank or all white space.)

Token API Request

The basic syntax for getting a token is to make a GET request as follows:

https://api.targeting.foursquare.com/token/user?email=email_address&first_name=first_name&last_name=last_name&KEY=api_key

• As per any http GET request parameter, the email address and first/last names must be URL-encoded.
• The request must be transmitted securely through https.

Refresh Token API Request

Once you have received a successful token response containing a user id, you should request future tokens for that user simply using the user id:

https://api.targeting.foursquare.com/token/user/user_id?KEY=api_key

Token API Response

Responses to the Foursquare Targeting API contain a JSON object in the response body, in addition to metadata in the http headers and the http status code. The standard http response body will contain data conforming to the JSend convention, augmented with a few other attributes:

• status (success, fail, error)
• data (for success_/_fail)
• message (for error)
• version (API version)

Standard Response

An http 200 response will be accompanied with JSON, similar to the following, containing the user’s userId, token and the expiration date of the token:

{
  "version": 4,
  "status": "success",
  "data": {
    "uid": "fbd96e3a-1d7d-4a93-b201-020e53e65417",
    "token": "XTH4sYzIjP5cG6RzqSoi",
    "expiration": 1443650290
  }
}

You should forward both the token and expiration date to your clients. The expiration date will be in epoch time, in seconds.

Exceptional Paths

Using Tokens

Once your client has a token and expiration date, it can make API requests directly to Foursquare Targeting. In order to make requests to Foursquare Targeting:

1. Ensure that the expiration date for the token has not passed. If it has, your client-side code should be prepared to ask your server for a new token, which it will have to fetch from Foursquare Targeting.
2. Insert the valid token into the Authorization header as an OAuth 2.0 Bearer token.
   For example, if the token is XTH4sYzIjP5cG6RzqSoi, the header would look like:

GET /geopulse/designs/ HTTP/1.1
Host: api.targeting.foursquare.com
Authorization: Bearer XTH4sYzIjP5cG6RzqSoi

Refreshing Tokens

If the token has expired, your server simply needs to make a new request to the token API with the appropriate user id. Foursquare Targeting will return a new token.