There are two ways to authenticate to the Data SDK:

• Command Line (Suggested)
• Manual Token Retrieval

Command Line Authentication

To quickly authenticate via the command line, use the following command:

uf-data-sdk authenticate

Your browser will open a new page requesting permission to authorize. Click Accept to complete authentication.

Manual Authentication

Alternatively, users may choose to manually authenticate to the Data SDK. This method is not suggested, and is reserved for instances where command line authentication is failing or otherwise inaccessible.

Obtaining an Access Token

You can get an access token at:

https://studio.foursquare.com/tokens.html

This access token will allow API calls to access the same resources (maps, datasets, etc) that your user account is allowed to access in our application. The token will expire after a given time period, and you will need to visit this page again to get a new one. This token should be kept safe, as it will allow anyone who has it access to your data until it expires.

Refresh Tokens

A refresh token is a special kind of token used to acquire an access token. By default, the Data SDK uses refresh token rotation, which means that each time you use a refresh token, a new refresh token will be included in the response and the old token will be invalidated. This rotation reduces the risk of a compromised refresh token, but it means the caller is responsible for managing new refresh tokens as they are issued.

Non-rotating Refresh Tokens

You may want to disable refresh token rotation if you are operating in environments with read-only secrets (such as Databricks). Non-rotating tokens never expire, so users need to be more careful to keep them safe. For that reason, unless you specifically need to support an environment with read-only secret access, we recommend our default refresh tokens. To enable non-rotating refresh tokens, the following flags are recommended.

$ uf-data-sdk authenticate --non-rotating --print --no-store-credentials

You can get a refresh token at:

https://studio.foursquare.com/tokens.html

Authentication Errors

API calls that are unauthorized, do not include a token, include an expired or malformed token, etc., will return an appropriate error in the response.

Use Tokens

If you are using the REST API, you need to provide the access token in each request.

If you are using a language specific binding, authentication with a refresh token only needs to be done once

from unfolded.data_sdk import DataSDK
data_sdk = DataSDK(refresh_token='v1.ABC...')

uf-data-sdk store-refresh-token

curl -X POST https://data-api.foursquare.com/v1/datasets/data?name=My+Dataset
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: text/csv'
--data-binary '@/path/to/my_dataset.csv'

Parameters

Authentication Errors

API calls that are unauthorized, do not include a token, include an expired or malformed token, etc., will return an appropriate error in the response.