# FreeAgent — Accounting API: connection

> Canonical URL: https://developers.apideck.com/apis/accounting/freeagent/connection

# 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](https://support.freeagent.com/hc/en-gb/articles/115001223444-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](#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](https://support.freeagent.com/hc/en-gb/articles/360007347980-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](https://support.freeagent.com/hc/en-gb/articles/115001223444-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](#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](https://help.apideck.com/en/articles/7774658).


[API reference](https://developers.apideck.com/apis/accounting/reference.md) · [Coverage matrix](https://developers.apideck.com/apis/accounting/coverage)