Skip to main content

Authorization

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

FreeAgent

Prerequisites​

FreeAgent uses OAuth 2.0 to authenticate API access. Before creating a FreeAgent credential in Nexla, you must register an application in the FreeAgent Developer Dashboard to obtain an OAuth Client ID and Client Secret.

Register an Application in the FreeAgent Developer Dashboard​

  1. Sign in to the FreeAgent Developer Dashboard using your FreeAgent account credentials. If you do not yet have a developer account, create one at the same URL.

  2. Click Create App (or New App) to register a new application.

  3. Enter a descriptive name for the application in the App Name field (for example, "Nexla Integration").

  4. In the Redirect URI field, enter the OAuth callback URL provided by Nexla. This URI must exactly match a redirect URI registered in your Developer Dashboard account; mismatches will cause the authorization flow to fail.

  5. Select the Access Level appropriate for your integration. FreeAgent uses a numeric access level system (0–8) that controls which resources your app can read or write. Choose the minimum level that covers your required data — for example, read access to invoices, contacts, bank transactions, and expenses. Requesting a higher level than necessary may slow down app approval.

  6. Click Save (or Create App) to register the application.

  7. After registration, your OAuth Identifier (Client ID) and OAuth Secret (Client Secret) are displayed on the application detail page. Copy both values and store them securely — the Client Secret cannot be retrieved again after you navigate away from this page.

FreeAgent provides a sandbox environment for testing integrations without affecting live data. To test your Nexla integration before connecting to production data, sign up for a free sandbox account at https://sandbox.freeagent.com and use the sandbox API base URL (https://api.sandbox.freeagent.com/v2) during testing. For complete OAuth documentation, see the FreeAgent OAuth guide.

Create a FreeAgent Credential​

  • To create a new FreeAgent 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.

OAuth 2.0 Authentication​

FreeAgent uses the OAuth 2.0 Authorization Code flow to grant Nexla access to your FreeAgent account. Nexla handles the token exchange and refresh automatically after you provide your application credentials.

  1. Enter your FreeAgent OAuth Identifier (Client ID) in the OAuth Identifier field. This is the unique identifier for the application you registered in the FreeAgent Developer Dashboard.

  2. Enter your FreeAgent OAuth Secret (Client Secret) in the OAuth Secret field. This secret is used in combination with the Client ID to authenticate your application during the token exchange.

    Important

    Your OAuth Secret is sensitive. Treat it like a password — never share it publicly or commit it to version control. If the secret is compromised, regenerate it immediately in the FreeAgent Developer Dashboard.

  3. Click the Authorize button (or equivalent OAuth connect button) to initiate the OAuth 2.0 authorization flow. You will be redirected to FreeAgent to sign in and grant the requested permissions to the registered application.

  4. After granting access, FreeAgent will redirect you back to Nexla with an authorization code. Nexla automatically exchanges this code for an access token and refresh token.

    FreeAgent access tokens are valid for one hour. Nexla automatically uses the refresh token to obtain a new access token when needed, so re-authorization is not required for ongoing integrations. Refresh tokens are long-lived (approximately 20 years), ensuring persistent access without repeated user authorization.

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. The newly added credential will now 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.