FreeAgent API — Level 6 payment permissions and Mettle bank balances

Authentication
1

Hello FreeAgent API team,

I’m investigating a secure daily banking data integration for Kaizen Accommodation Ltd.

My Mettle business bank account is already connected to FreeAgent, and transactions and the displayed balance are updating successfully.

I want to retrieve transactions and balances automatically through the FreeAgent API into Google Sheets.

Before proceeding, could an engineer please clarify:

  1. Can an OAuth application authorised by a dedicated Level 6 Banking user initiate, authorise or execute payments from the linked Mettle bank account through any API endpoint or related feature?
  2. Are there genuinely read-only OAuth scopes that prevent changes to accounting records?
  3. Does the bank account API’s current_balance represent the actual Mettle bank-reported balance or a FreeAgent-calculated accounting balance?
  4. Can the integration retrieve transactions and balances daily using OAuth refresh tokens without daily manual authorisation?

My essential requirement is that the integration’s permissions must technically prevent bank payment initiation. I do not want to rely merely on application code behaving as read-only.

No API application has been deployed yet. I’m seeking confirmation before implementation.

Thank you for your help.

2

Hi, I’m James, one of the FreeAgent engineers.

To answer your core concern, you cannot perform any kind of payment actions on a Mettle account through the FreeAgent API. While you can perform various actions on bank transactions as they are represented in FreeAgent, write operations that feed back to Mettle are strictly limited to explaining or categorising transactions.

Addressing your specific points:

  1. No. An OAuth application authorised via FreeAgent cannot initiate or execute payments from the linked Mettle account.
  2. Access and scope: There are no dedicated read-only OAuth scopes. However, permissions are governed by the user’s access level in FreeAgent. If the authorised user is set up without Banking access, any API application connected through their credentials will inherit that restriction, technically preventing payment related operations.
  3. Current balance: The current balance is calculated on the FreeAgent side based on recorded transactions, it is not the raw real time Mettle bank reported balance, though they ideally correspond.
  4. Refresh tokens: Yes, the integration can retrieve transactions and balances daily using OAuth refresh tokens without requiring daily manual re-authorisation.