Connect to the Alpha API

Use the OAuth 2.0 authentication standard to authenticate to the FreshBooks Alpha APIs.

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

Register Your Application

To obtain the OAuth client credentials:

1. Log into the FreshBooks developers site at https://my.freshbooks.com/#/developer and click Create an App.
2. Enter information to be displayed to your users when they are prompted to grant permissions to your app.
3. Specify a redirect URI.

   Set the redirect URI to https://localhost:33333/, or some other similar https url.

   If you are making a Web application, set the Callback URL to a page on your Web app you would like the user to be returned to after they have authorized your application.

Authenticate to FreshBooks from a Desktop Application

After setting the following connection properties, you are ready to connect:

• OAuthClientId: Set this to the name of the company you are connecting to.
• OAuthClientSecret: Set this to the consumer secret in your app settings.
• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the access token in the connection string.
• AccountId: Set this to connect to data. Query the IdentityInfo view to obtain this value.

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 following OAuth process:

1. Retrieves the OAuthAccessToken and OAuthAccessTokenSecret and authenticates requests.
2. Refreshes the access token when it expires.
3. Saves OAuth values to be persisted across connections.

Authenticate to FreshBooks from a Web Application

To obtain the access token, set the following connection properties:

• OAuthClientId: Set this to the name of the company you are connecting to.
• OAuthClientSecret: Set this to the consumer secret in your app settings.

When you connect via a Web application, or if the driver is not authorized to open a browser window, you need to exchange temporary verification values for the access token:

1. Call GetOAuthAuthorizationURL. The stored procedure returns the URL to the FreshBooks OAuth endpoint.
2. Log in at the OAuth endpoint and authorize the app. You are redirected back to the callback URL.

   The callback URL contains the verifier code in a query string parameter. The parameter is named "oauth_verifier". Extract the verifier code from the callback URL.

3. Call GetOAuthAccessToken. The stored procedure returns the access token.

To connect to data, set the following connection properties:

• AccountId
• OAuthClientSecret
• OAuthAccessToken
• OAuthAccessTokenSecret

Note: To obtain an AccountId, query the IdentityInfo view to obtain this value.

Refresh the Token

To automatically refresh the access token when it expires, set InitiateOAuth to REFRESH and set OAuthRefreshToken. Alternatively, when the access token expires, call the RefreshOAuthAccessToken stored procedure to refresh the access token.