How to connect FreeAgent

Connecting FreeAgent takes one action: authorize the connection by signing in to FreeAgent. There are no credentials to copy and paste and no fields to fill in afterwards. Apideck runs the OAuth flow and refreshes the access token for you, so the connection keeps working without you re-entering anything.

One thing is worth deciding before you start: the connection reads and writes with the FreeAgent permissions of whoever authorizes it. Sign in with the right account and the setup is finished in a couple of clicks.

Prerequisites

• An active FreeAgent subscription. Any FreeAgent plan works.
• A FreeAgent user account in the company you want to connect, with a password you can sign in with.
• Enough access in FreeAgent for what the integration needs to do. FreeAgent grades each user on an eight-level access scale, and the connection inherits the level of the account that authorizes it. The required level varies by area: ledger accounts, for example, need only My Money (level 2), while journal entries and the balance sheet and profit-and-loss reports sit behind Tax, Accounting & Users (level 7) or higher. So a user at FreeAgent's highest access level, which FreeAgent's API documentation calls level 8 or Full, is the safest choice when the integration needs the complete picture. A lower-level user can still authorize successfully, but the areas above their level are not available to the connection. FreeAgent explains the scale in User access levels in FreeAgent; levels are set under Settings > Users (from the drop-down menu under the business name) by a user who is allowed to manage users.

You do not need to install anything in FreeAgent, enable a module, or ask FreeAgent to switch a feature on first.

1. Start the authorization

1. Open the FreeAgent connection in Apideck Vault.
2. Click Authorize. You are redirected to FreeAgent.

2. Sign in to FreeAgent and approve access

1. Sign in with your FreeAgent email address and password.
2. Check the application name shown on FreeAgent's approval screen, then approve.

Your FreeAgent password is used by FreeAgent only. You type it on FreeAgent's own sign-in page during this flow, and it is never shared with the application you are connecting to or stored by Apideck. What the application receives is a token that FreeAgent issues, and that you can withdraw at any time (see Revoking access).

There are no per-permission choices to make on that screen. FreeAgent's OAuth flow has no scope parameter, so there is no scope list to narrow: approving grants the application access at your own FreeAgent permission level, which is why the access level of the account you sign in with is the thing that matters. The one item worth checking is the application name. It is the application belonging to the provider whose integration you are setting up, or Apideck when the integration is still using Apideck's shared credentials for testing. If you do not recognise the name, raise it with that provider rather than approving now and unwinding later.

Complete the flow in one sitting. FreeAgent's authorization code expires 15 minutes after it is issued, so if you pause partway, close the tab, or the redirect back to Vault is interrupted, return to Vault and click Authorize again.

3. That is the whole setup

FreeAgent redirects you back to Vault and the connection is ready. There is nothing further to enter: this connector asks for no subdomain, no region, no account or company identifier, and no API key. If you are looking for a second screen of settings, there isn't one.

Notes

• Token refresh is automatic. Apideck refreshes the short-lived access token for you. There is no expiry date to diary and nothing to re-enter while the connection is in regular use.
• Your access governs the connection's access. If your FreeAgent access level is lowered, or your user is deactivated or removed, the connection loses the same access. Tell whoever manages your FreeAgent users before changing the access level of an account that authorized a connection.
• A connection reaches the FreeAgent company of the account that authorized it. If you are an accountant or bookkeeper who needs one connection to reach several client companies, say so to the provider whose integration you are setting up: that uses FreeAgent's separate Accountancy Practice API, which FreeAgent enables on request rather than self-serve, and it is the provider who arranges it.
• Sandbox and production FreeAgent accounts are separate. Which of the two a connection points at is decided by the integration you are setting up, not by you, and the two sets of sign-in details are not interchangeable. If you were given sandbox account details for testing, use them only on the connection intended for testing.

Revoking access

You can withdraw the connection's access from inside FreeAgent at any time, without involving the provider:

1. Open the drop-down menu under your business name in FreeAgent and select Connections & Add-ons.
2. In the Approved applications section, select Manage.
3. Remove access for the application you no longer want connected.

FreeAgent documents these screens in Manage your connections.

After you revoke, the connection stops returning FreeAgent data. To reconnect, open the connection in Vault and click Authorize again.

Troubleshooting

Authorization failed, or FreeAgent reported an invalid or expired code. The authorization code expires 15 minutes after it is issued. Start again from Vault with Authorize and complete sign-in and approval without pausing.

The connection authorized, but one area of data errors or comes back short. This is usually the access level of the account that authorized it, not a broken connection: the connection can only reach what that FreeAgent user can reach, and areas above that level are not available to it. Check the level under Settings > Users (from the drop-down menu under the business name) against User access levels in FreeAgent, then re-run Authorize with an account that has the access the integration needs: journal entries, the balance sheet and profit-and-loss are the areas that need Tax, Accounting & Users (level 7) or higher. If the access level is already sufficient, check the same area directly in FreeAgent, since an area with no records there will also have none here.

My FreeAgent sign-in is rejected. Confirm you can sign in to FreeAgent directly in a browser with the same email address and password first. If that works and the connection still rejects it, check you are not using sandbox account details on a production connection, or the reverse, and report the mismatch to the provider whose integration you are setting up.

The connection worked and later stopped. The usual causes, in order:

1. Access was withdrawn in Connections & Add-ons > Approved applications for the FreeAgent account that authorized it (see Revoking access).
2. That user's access level was reduced, or the user was deactivated or removed.

Both are fixed by opening the connection in Vault and clicking Authorize again, with an account that has the access you need. If neither applies, check the standing of the FreeAgent account itself with FreeAgent.

Requests are being throttled or slowing down. FreeAgent counts its request limits against the individual user who authorized the integration, and throttling clears on its own at the start of the next minute or hour. The connector overview lists the current limits.

Still stuck? Contact Apideck Support.