You can use a personal access token to authenticate to Square or use the OAuth standard. Use a personal token to access your own data or to test through the sandbox. Use OAuth to enable other users to access their own data.

Using a Personal Access Token

Set the OAuthAccessToken connection property to your personal token, which can be obtained by following the steps below:

1. Navigate to the Developer Dashboard and see Create an OAuth App for creation guide.
2. Once the app is created, the token is listed on the Credentials tab.

Using the Square Sandbox

Version 2 of the Connect API allows you to test in a sandbox environment. Transactions created in the sandbox are not sent through to card networks, and cards are never charged.

To connect to the sandbox, set OAuthAccessToken to the sandbox access token, which is available alongside your standard personal access token:

1. Navigate to the Developer Dashboard and see Create an OAuth App for creation guide.
2. Once the app is created, the sandbox token is listed on the Credentials tab.

Using OAuth

OAuth requires the authenticating user to interact with Square using the browser. The driver facilitates this in various ways as described below.

Authenticate to Square from a Desktop Application

You can connect without setting any connection properties for your user credentials. After setting InitiateOAuth to GETANDREFRESH, you are ready to connect. You can use the GETANDREFRESH configuration to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.

When you connect, the driver opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The driver then completes the OAuth process.

1. Extracts the access token from the callback URL and authenticates requests.
2. Obtains a new access token when the old one expires.
3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Note: The driver is already registered with Square as an OAuth application and will automatically use its embedded OAuthClientId and OAuthClientSecret to connect. If you want to use your own custom OAuth app, see Create an OAuth App to obtain these connection properties.

Authenticate to Square from a Web Application

When connecting via a Web application, or if the driver is not authorized to open a browser window, you need to register an application with Square (see Create an OAuth App). You can then use the driver to get and manage the OAuth token values.

Get an Access Token

Set the following connection properties to obtain the OAuthAccessToken:

• OAuthClientId: Set this to the Application Id in your app settings.
• OAuthClientSecret: Set this to the Application Secret in your app settings.

You can then call stored procedures to complete the OAuth exchange:

1. Call the GetOAuthAuthorizationURL stored procedure. Set the AuthMode input to WEB and set the CallbackURL input to the Redirect URI you specified in your app settings. The stored procedure returns the URL to the OAuth endpoint.
2. Log in and authorize the application. You are redirected back to the callback URL.
3. Call the GetOAuthAccessToken stored procedure. Set the AuthMode input to WEB. Set the Verifier input to the "code" parameter in the query string of the callback URL.

Connect to Data and Refresh the Token

Set the OAuthAccessToken returned by GetOAuthAccessToken to connect to data. This token has a limited lifetime. To automatically refresh the token, set the following on the first data connection. Alternatively, use the RefreshOAuthAccessToken stored procedure to manually refresh the token.

• LocationId: Set this to specify a default business location in the connection string or set the LocationId in the query. A LocationId must be specified to retrieve data.
• InitiateOAuth: Set this to REFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
• OAuthSettingsLocation: Set this to the path where the driver will save the OAuth values, to be persisted across connections.
• OAuthClientId: Set this to the Application Id in your app settings.
• OAuthClientSecret: Set this to the Application Secret in your app settings.
• OAuthRefreshToken: Set this to the refresh token returned by GetOAuthAccessToken.
• OAuthAccessToken: Set this to the access token returned by GetOAuthAccessToken.

On subsequent data connections, set the following:

• LocationId
• InitiateOAuth
• OAuthSettingsLocation