Connecting

Registration

Start by registering your app to obtain its Foursquare API credentials. Be sure to use an account with a secure password to own these credentials. If you're creating an app on the behalf of a full-fledged company, consider creating the app using the page account for your company or create a new Foursquare account associated with a broader corporate email address.

Since each set of credentials is tied to a particular URL, you may also want to create different credentials for your development server and production server. For the purposes of OAuth, your “key” from that registration process is your “client id” here, and your secret from registering is your secret here.

After registering your app, please do your best to protect your client secret. We strongly discourage embedding your secret in the clear in released code or binaries. Be prepared to rotate your secret if it is discovered it is compromised in any way.

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.

iOS or Android applications may use our native flow to obtain a Foursquare access token. Developers on other platforms (mobile or desktop) can use one of our two web-based flows -- code and token -- to authenticate users and obtain an access token.

Native (Preferred)

Native auth is the easiest way for users to connect with Foursquare. Unlike web-based OAuth, the native flow re-uses the Foursquare app’s user credentials, 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.

Code (Preferred)

Web server applications

  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.

Token flow

Client applications

If you have no substantive server code, you can use the token flow outlined below. If your app is pure Javascript, you can easily parse the token from the URL.

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

Pow! That’s all there is to it.

Authentication

The examples above use /authenticate instead of /authorize, which what the OAuth protocol specifies. Following precedent established by Twitter and LinkedIn, /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 access

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, wap, 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

OAuth can pass secrets in the clear without requiring manual signing of requests. The catch is that all requests must be via HTTPS, and you’ll see errors when not using HTTPS.

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

Some OAuth libraries expect to pass the OAuth token as access_token instead of oauth_token, since this is the expectation created by Facebook, at odds with earlier versions of the OAuth spec. We may add support for both parameter names, depending on feedback, but for now know that this may come up.

The OAuth spec provides for Resource Owner Password Credentials, exchanging the user’s password for a token, but we do not allow third-party clients to use this flow for security reasons.

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 in the future. 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.