Authentication

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.

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'

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
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:

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:

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

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

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 --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:

{
  "access_token": "string"
}

3rd Party Authentication

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.

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.

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.

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.

{
  "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 --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.

4. (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.

To create a session token, use the Users Session Token endpoint and authenticate using the user's access_token obtained in Step 3.

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.

{
  "session_token": "SESSION_TOKEN"
}

You will use this token as a parameter in the Placemaker UI URL: https://foursquare.com/placemakers/home?session_token=<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.