Skip to main content

Authorization

Follow this guide to create a new FreshBooks credential that will allow Nexla to authenticate to and exchange data with your FreshBooks account.
fresh_books_api_auth.png

FreshBooks

Prerequisites​

FreshBooks uses OAuth 2.0 (3-legged authorization code flow) for API authentication. Before creating a FreshBooks credential in Nexla, you must register a developer application in FreshBooks to obtain a Client ID and Client Secret.

Register a FreshBooks Developer Application​

  1. Sign in to your FreshBooks account at https://my.freshbooks.com, or create a new account at https://www.freshbooks.com if you do not already have one.

  2. Navigate to the FreshBooks Developer Portal at https://my.freshbooks.com/#/developer.

  3. Click the Create App button to begin registering a new OAuth application.

  4. Complete the application registration form with the following information:

    • Application Name: Enter a descriptive name for your integration (e.g., "Nexla Integration").

    • Redirect URI: Enter the redirect URI provided by Nexla. This is the URL to which FreshBooks will send users after they authorize access. Nexla's OAuth redirect URI is https://app.nexla.io/oauth/callback.

    • Application Description: Optionally, provide a description of what the application does.

  5. Click Save to create the application.

  6. After the application is saved, scroll down to the App Settings section to locate your credentials:

    • Client ID: A unique public identifier for your application.

    • Client Secret: A private key used to authenticate your application when requesting tokens. Copy and store this value securely—FreshBooks does not display the secret again after you navigate away from the App Settings page.

Important

Store your Client Secret in a secure location immediately after copying it. If you lose it, you will need to regenerate it, which will invalidate all existing tokens issued to your application.

Locate Your FreshBooks Account ID and Business ID​

The FreshBooks API uses two types of identifiers to scope requests:

  • Account ID: Used by accounting endpoints (clients, invoices, expenses, taxes, payments). Formatted as a short alphanumeric string (e.g., MJx3p).

  • Business ID: Used by time tracking and project endpoints.

Both identifiers can be retrieved after authenticating by calling the GET https://api.freshbooks.com/auth/api/v1/users/me endpoint. In the response, locate the business_memberships array—each entry contains an account_id and a business_id for the accounts and businesses associated with your FreshBooks user.

For more details, refer to the FreshBooks API documentation.

Create a FreshBooks Credential​

  • To create a new FreshBooks credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

FreshBooks OAuth 2.0 Authentication​

FreshBooks uses a 3-legged OAuth 2.0 flow, which requires the account owner to log in and explicitly grant Nexla permission to access their FreshBooks data. This is the standard authorization method required by FreshBooks for all third-party integrations.

  1. In the Authorization URL field, verify or enter the FreshBooks authorization endpoint. This field is pre-filled with the default value https://auth.freshbooks.com/oauth/authorize.

  2. Enter your FreshBooks application's Client ID in the Client ID field. This is the public identifier obtained when you registered your developer application in the FreshBooks Developer Portal.

  3. Optionally, enter a space-separated list of OAuth permission scopes in the Access Scope field. FreshBooks scopes control which resources the credential can access. Leave this field blank to request the default set of permissions associated with your registered application.

    For most integrations, leaving the Access Scope field blank will grant access to all resources your FreshBooks application is authorized to use. Refer to the FreshBooks API Authentication documentation for a complete list of available scopes.

  4. In the Token URL field, verify or enter the FreshBooks token endpoint. This field is pre-filled with the default value https://api.freshbooks.com/auth/oauth/token.

  5. Enter your FreshBooks application's Client Secret in the Client Secret field. This is the private key obtained from the App Settings section of your FreshBooks developer application. This value is treated as a password and will be stored securely.

  6. In the Base URL field, verify or enter the FreshBooks API base URL. This field is pre-filled with the default production value. Select Production (https://api.freshbooks.com) from the dropdown or keep the pre-filled value unless your organization requires a different base URL.

    The Base URL is used to construct all API requests made by this credential. In most cases, the default production URL is the correct value.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential.

  2. Nexla will redirect you through the FreshBooks OAuth login and consent screen. Sign in to FreshBooks with the account you wish to connect, and click Allow to grant Nexla access to your FreshBooks data.

  3. After authorization is complete, the newly added credential will appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.