Authentication Methods for the Places API

Select the authentication method for the Places API that best aligns with your requirements for user tracking, edit attribution, and overall user management.

Service Keys

You may use Service Keys to authenticate requests for the Places API and Users API.

Authenticating against the API is done by passing your Service Key through an Authorization: Bearer header parameter.

Example Usage

cURL

curl --request GET \
     --url https://places-api.foursquare.com/places/search \
    --header 'Authorization: Bearer <Service API Key>' \
    --header 'X-Places-Api-Version: 2025-06-17'

Python

import requests

url = "https://api.foursquare.com/v3/places/search"

headers = {
    "Accept": "application/json",
    "Authorization": "12345"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

PHP

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.foursquare.com/v3/places/search', [\
  'headers' => [\
    'Accept' => 'application/json',\
    'Authorization' => '12345',\
  ],\
]);

echo $response->getBody();

Learn how to View and Manage Your Service API Keys via the Developer Console.

Managed Users

You can use the Users API to enable per-user tracking and attribution without your users needing Foursquare accounts. As these APIs are called by your application, they authenticate with Service Keys, which are attributed to your application as a whole. They return Managed User Keys.

Call the Users API to create managed users. Simply provide an optional first and last name to identify the user:

Example Usage

cURL

curl --request POST \
     --url 'https://users-api.foursquare.com/users/managed-user/create?first_name=John&last_name=Smith' \
     --header 'X-Users-Api-Version: 2025-06-17' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <ORGANIZATION_SERVICE_KEY>'

Successful user creation calls return a user_id and an access_token:

JSON Response

{
  "user_id": 0,
  "access_token": "string"
}

This access token can be used to make Places API calls, e.g.:

cURL

curl --request GET \
     --url https://places-api.foursquare.com/places/search \
    --header 'Authorization: Bearer <Access Token>' \
    --header 'X-Places-Api-Version: 2025-06-17'

Refresh Managed User Access Token

Pass the user_id as a query parameter to the Refresh Managed User endpoint to retrieve a new access token, e.g.:

cURL

curl --request POST \
     --url 'https://users-api.foursquare.com/users/managed-user/refresh-token?target_user_id=1234' \
     --header 'X-Users-Api-Version: 2025-06-17' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <ORGANIZATION_SERVICE_KEY>'

Successful fresh user access token calls return an access_token:

JSON Response

{
  "access_token": "string"
}

3rd Party Authentication ( Enterprise Customers Only)

We recommend the following workflow for authorizing your application to access the Foursquare API on behalf of a user using the OAuth 2.0 authorization code grant type.

1. Direct User for Authorization

Initiate the authorization flow by directing the user's browser to the Foursquare authorization endpoint. This request includes your application's client ID, the desired response type (code), and the registered redirect URI where the user will be sent after granting or denying access.

HTTP Request

https://app.foursquare.com/oauth2/authenticate
    ?client_id=YOUR_CLIENT_ID
    &response_type=code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI

Query Parameters:

2. Handle the Redirect and Authorization Code

If the user successfully grants your application permission, Foursquare will redirect their browser back to your specified redirect_uri. The authorization code will be included as a query parameter.

HTTP Request

https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE

Query Parameters:

Your application's server-side code at the redirect_uri should extract this code parameter.

3. Exchange Authorization Code for Access Token

Your server must exchange the authorization code received in Step 2 for a permanent access token. This is a server-to-server request and should not be done client-side. Securely store the access_token returned with its associated user in your database.

HTTP Request

https://app.foursquare.com/oauth2/access_token
    ?client_id=YOUR_CLIENT_ID
    &client_secret=YOUR_CLIENT_SECRET
    &grant_type=authorization_code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
    &code=CODE

Query Parameters:

Response:

If the exchange is successful, the API will return a JSON object containing the access token.

JSON Response

{
  "access_token": "ACCESS_TOKEN"
}

4. Make Authenticated API Requests

Once you have obtained an access_token, you can use it to make requests to Foursquare API endpoints that require authentication. Include the access token in the Authorization header of your requests using the Bearer scheme.

cURL

curl --request GET \
     --url https://places-api.foursquare.com/places/search \
    --header 'Authorization: Bearer <ACCESS_TOKEN>' \
    --header 'X-Places-Api-Version: 2025-06-17'

Replace <ACCESS_TOKEN> with the actual access token obtained in Step 3.

(Optional) Embed Foursquare's Placemaker UIs directly into your application

When using 3rd Party Authentications where your users have Foursquare accounts, you can pop a pre-authenticated web view of our Placemaker UIs where users can provide edits to Foursquare places data, vote on pending edits, and more. In order to access these pre-authenticated Placemaker UIs, you will need to subsequently create a short-lived session token.

cURL

curl --request POST \
     --url 'https://users-api.foursquare.com/auth/session-token' \
     --header 'X-Users-Api-Version: 2025-06-17' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <USERS_ACCESS_TOKEN>'

Response:

If the exchange is successful, the API will return a JSON object containing a short-lived session token.

JSON Response

{
  "session_token": "SESSION_TOKEN"
}

You will use this token as a parameter in the Placemaker UI URL: < https://foursquare.com/placemakers/home?session_token= >. This will launch a web view that is authenticated for your user and their activity is associated with your application. Note that this token expires after 10 minutes, so if it is no longer valid you will need to re-call the session-token endpoint to generate a new token.