# Authentication

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

| Authentication Method                                     | Intended Use                                                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                             |
| :-------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Service Keys](#service-keys)**                         | Userless Interfaces, Quick Testing, Internal Automation, Background Processes                | For scripts, agents, internal tools, or ad-hoc/quick one-time API calls. Easy setup in the Developer Console. Edits and calls attributed to your organization.                                                                                                                                                                                                                                                          |
| **[Managed Users](#managed-users)**                       | Integrating Features Natively<br />**(Your users *don't have or need* Foursquare accounts)** | Integrate Places API calls without requiring users to have or interact with Foursquare accounts directly. Enables per-user tracking and attribution. When used in conjunction with the Placemaker APIs, having per-user attribution allows us to evaluate the accuracy of edits coming from users individually, allowing your highest quality users to push edits through more quickly. Utilizes the Managed User APIs. |
| **[3rd Party Authentication](#3rd-party-authentication)** | Integrating with Foursquare User Accounts<br />**(Your users *have* Foursquare Accounts)**   | Enable your users to connect Foursquare accounts to your application for API access and potentially embedded Placemaker UIs. Allows users to control the connection. **Note: this is for enterprise customers only.**                                                                                                                                                                                                   |

## Service Keys

You may use [Service Keys](https://docs.foursquare.com/developer/docs/manage-service-api-keys) to authenticate requests for the Places API and Users API.

Authenticating against the API is done by passing your [Service Key](https://docs.foursquare.com/developer/docs/manage-service-api-keys) through an `Authorization: Bearer` header parameter.

```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](https://docs.foursquare.com/fsq-developers-users/docs/manage-service-api-keys) via the Developer Console.

## Managed Users

You can use the [Users API ](managed-user-create) 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](managed-user-create). Simply provide an optional first and last name to identify the user:

```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
{
  "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](managed-user-refresh-token) 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
{
  "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
https://app.foursquare.com/oauth2/authenticate
    ?client_id=YOUR_CLIENT_ID
    &response_type=code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
```

**Query Parameters:**

| Parameter       | Requirement | Description                                                                                                                                                                                          |
| :-------------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`     | required    | Your application's unique client ID.                                                                                                                                                                 |
| `response_type` | required    | Must be set to `code` for the authorization code grant flow.                                                                                                                                         |
| `redirect_uri`  | required    | The pre-registered URI in your application's settings where Foursquare will redirect the user.                                                                                                       |
| `mode`          | optional    | Optional string parameter that specifies the application context.<br />`mode=placemaker` - Uses the Placemaker-specific authorization interface<br />If omitted, uses the default authorization page |

### 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
https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE
```

**Query Parameters:**

| Parameter | Description                                                                                        |
| :-------- | :------------------------------------------------------------------------------------------------- |
| `code`    | A temporary authorization code that will be used in the next step to exchange for an access token. |

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

| Parameter       | Requirement | Description                                                   |
| :-------------- | :---------- | :------------------------------------------------------------ |
| `client_id`     | required    | Your application's unique client ID.                          |
| `client_secret` | required    | Your application's client secret. **Keep this confidential.** |
| `grant_type`    | required    | Must be set to `authorization_code`.                          |
| `redirect_uri`  | required    | Must exactly match the `redirect_uri` used in Step 1.         |
| `code`          | required    | The authorization code received in Step 2.                    |

**Response:**

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

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

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