Power BI Connector for FreshBooks

Build 20.0.7587

Creating a Custom OAuth App

Connecting to the Classic API

There are two methods you can use to connect to the FreshBooks Classic API, the authentication token specific to your login or OAuth 1.0. The authentication token method is deprecated and will not be supported by FreshBooks in the future.

Using the Authentication Token to Connect to FreshBooks

To connect to FreshBooks using an authentication token, specify the CompanyName and Token connection properties. The token can be found by logging in to FreshBooks and navigating to My Account > FreshBooks API.

Using OAuth to Connect to FreshBooks

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

Register Your Application

To obtain the OAuth client credentials:

  1. Request Developer Access through FreshBooks, if you have not already done so.
  2. Select My Account > FreshBooks API.
  3. Select the Use OAuth option and enter the application details. The details are displayed to users when they log in to grant permissions to the application. The OAuth consumer secret is displayed.

Note: It may take some time for FreshBooks to approve your registration.

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. Note that you can also use the CompanyName.
  • 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.

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

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

Authenticate to FreshBooks from a Web Application

To obtain the access token, set the following connection properties and follow the steps below:

  • OAuthClientId: Set this to the name of the company you are connecting to. Note that you can also use the CompanyName property.
  • OAuthClientSecret: Set this to the consumer secret in your app settings.

When you connect via a Web application, or if the connector 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:

  • CompanyName
  • OAuthClientSecret
  • OAuthAccessToken
  • OAuthAccessTokenSecret

Refresh the Token

To automatically refresh the access token when it expires, set InitiateOAuth to REFRESH and set OAuthRefreshToken. When the access token expires, call GetOAuthAccessToken to refresh the access token.

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 connector 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. Note that you can also use the CompanyName.
  • 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 connector opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The connector 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. Note that you can also use the CompanyName property.
  • OAuthClientSecret: Set this to the consumer secret in your app settings.

When you connect via a Web application, or if the connector 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.

Copyright (c) 2020 CData Software, Inc. - All rights reserved.
Build 20.0.7587