Connecting

Registration

Start by registering your app to obtain its Foursquare API credentials.

Access token

Access tokens allow apps to make requests to Foursquare on the behalf of a user. Each access token is unique to the user and consumer key. Access tokens do not expire, but they may be revoked by the user. If your application doesn't require connecting with Foursquare users, you can skip directly to Userless Access.

At this time, Foursquare only supports a single authentication mechanism that authorizes an application on behalf of both Foursquare and Swarm.

iOS / Android

Native auth is the easiest way for users to connect with Foursquare. Unlike the web-based OAuth flow documented below, our native flow leverages the Foursquare app already installed on your users’ phones, saving users the hassle of re-logging in to Foursquare within your app. Native auth is the only flow that supports users logging in to Foursquare using Facebook.

To use native auth, incorporate our utility classes for iOS or Android into your app. Additional instructions are provided in the repositories' README files.

Web Applications Code Flow

Here is the recommended OAuth 2.0 flow:

  1. Direct users to
    https://foursquare.com/oauth2/authenticate
        ?client_id=YOUR_CLIENT_ID
        &response_type=code
        &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
                      
    (generally done through a link or button)
  2. If the user accepts, they will be redirected back to
        https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE
                      
  3. Your server should exchange the code it got in step 2 for an access token. Make a request for
    https://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
                      
  4. The response will be JSON
    { access_token: ACCESS_TOKEN }
                      
  5. Save this access token for this user in your database.

Web Applications Token Flow

Client applications

If you have no substantive server code, you can use the token flow outlined below.

  1. Redirect users who wish to authenticate to
    https://foursquare.com/oauth2/authenticate
        ?client_id=CLIENT_ID
        &response_type=token
        &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
                
  2. If a user accepts, they will be redirected back to
    https://YOUR_REGISTERED_REDIRECT_URI/#access_token=ACCESS_TOKEN
                

If register multiple redirect URIs for your app, you can specify which URI to use by changing the value of the redirect_uri parameter. If you enable web connect, your users will be redirected to your first redirect URI.

Requests

Once you have an access token, it’s easy to use any of the endpoints, by just adding oauth_token=ACCESS_TOKEN to your GET or POST request. For example, from the command line, you can do

curl https://api.foursquare.com/v2/users/self/checkins?oauth_token=ACCESS_TOKEN&v=YYYYMMDD
          

Authentication

The examples above use /authenticate instead of /authorize, which what the OAuth protocol specifies. It is worth noting that /authenticate handles both user authentication and app authorization and automatically redirects if a user has already authorized the calling app. Conversely, /authorize will prompt the user to accept the the auth request every time.

We encourage web apps to use session cookies to verify a user's identity once the user has been initially authenticated. All embedded webviews inside of Foursquare share the same cookies, so all subsequent interactions can rely on the session cookie to authenticate the user, avoiding server redirects each time the user interacts with the app.

Userless Server Integrations

Some of our endpoints that don’t pertain to specific user information, such as venues search are enabled for userless access (meaning you don’t need to have a user auth your app for access). To make a userless request, specify your consumer key's Client ID and Secret instead of an auth token in the request URL.

https://api.foursquare.com/v2/venues/search?ll=40.7,-74&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&v=YYYYMMDD
        

To see what level of permissions each endpoint needs, check out the filters at the top of our endpoints page.

Display Types

By default, Foursquare auto-detects the appropriate type of site to display for the auth dialog. You can force a specific display type by adding display=XXX to your authorize or authenticate URLs. The supported display types are touch, and webpopup. We don't recommend specifying a display type, unless you are using the webpopup display. In webpopup mode, we pop up a new web window for the auth dialog, redirect to the callback in the caller window, and close the popup window after the user authorizes the app.

Notes on OAuth

Be sure to note that although API requests are against api.foursquare.com, OAuth token and authorization requests are against foursquare.com.

One issue you may run into on Android is that Foursquare uses a wildcard SSL cert. For more information, see this Stack Overflow answer.

Although at this time we do not expire OAuth access tokens, you should be prepared for this possibility. Also remember that a user may disconnect via the Foursquare settings page at any time. Using /authorize will ask the user to re-authenticate their identity and reauthorize your app while giving the user the option to login under a different account.