# FreeAgent — Accounting API: configuration

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

# How to create an OAuth app in FreeAgent

This guide explains how to register your own FreeAgent OAuth app and configure the Apideck FreeAgent connector with it, so your consumers authorize against your application instead of Apideck's.

If you only want to try the connector first, Apideck's shared credentials for testing let you connect without registering anything; register your own app before you go to production.

## Before you start, you'll need

1. A **FreeAgent Developer account** (free) to create apps and read their credentials: [dev.freeagent.com/signup](https://dev.freeagent.com/signup).
2. A **FreeAgent company to test against**. For development, create a free sandbox company at [signup.sandbox.freeagent.com/signup](https://signup.sandbox.freeagent.com/signup) and complete its setup stages before calling the API; an incompletely set-up company returns errors that look like connector faults.
3. An **Apideck account** with access to the [FreeAgent connector settings](https://platform.apideck.com/configuration/accounting/freeagent) in the Apideck Dashboard.

## 1. Create your app in the FreeAgent Developer Dashboard

FreeAgent's create-app form asks for everything below in one pass, so fill it in completely before you save.

1. Sign in to the [FreeAgent Developer Dashboard](https://dev.freeagent.com/) and open [My Apps](https://dev.freeagent.com/apps).
2. Select **Create New App**.
3. Enter your app's **name**. The app name is what your consumers see on FreeAgent's approval screen during the OAuth flow, so use your product's public name rather than an internal project name.
4. Add exactly this **redirect URI**:

   ```
   https://unify.apideck.com/vault/callback
   ```

   FreeAgent matches the `redirect_uri` in the authorization request against the URIs registered on the app, so a trailing slash, an `http://` scheme, or a localhost value will fail the flow rather than degrade it. Apideck always sends the value above.

5. Save the app, then reopen it to read its credentials (step 2).

Register a **separate app for sandbox and for production** (see step 3): the Developer Dashboard keeps a distinct credential pair per app, a sandbox pair cannot authorise a production company, and the Apideck redirect URI has to be registered on both apps. FreeAgent's [Quick Start guide](https://dev.freeagent.com/docs/quick_start) walks through the same dashboard screens if you want the vendor's own reference alongside this one.

## 2. Copy your credentials into Apideck

FreeAgent labels the credential pair **OAuth identifier** and **OAuth secret**; these are the standard OAuth client ID and client secret.

1. Open your app in the Developer Dashboard and copy the OAuth identifier and OAuth secret.
2. In the Apideck Dashboard, open the [FreeAgent connector settings](https://platform.apideck.com/configuration/accounting/freeagent) (**Configuration** > **Accounting** > **FreeAgent**).
3. Select **Use your own client credentials** and paste the OAuth identifier as the Client ID and the OAuth secret as the Client Secret.
4. Save the configuration.

That is the whole handoff on your side. Your consumers never receive or enter these credentials: they only sign in with their own FreeAgent email and password on FreeAgent's approval screen, and their password is never exposed to your application or to Apideck.

### Scopes and settings

- **Scopes**: FreeAgent's OAuth implementation has no scope parameter, so there is nothing to select or request. Authorization grants access at the authorizing user's own FreeAgent permission level, which is why a full-access user gives the most complete data.
- **Consumer settings**: none. The connector asks the consumer for no subdomain, region, or company identifier, so the Vault connection flow is OAuth-only.
- **Modules or add-ons**: none to enable on the FreeAgent side.
- **IP allow-listing**: not required.
- **Accountancy Practice API**: the standard Company API used by this connector is fully self-service. If your integration also needs an accountancy practice to reach client companies, that API is enabled per app on request only: email FreeAgent at integrationsrequests@freeagent.com to ask for a Practice sandbox, and ask your FreeAgent contact for an expected timeline.

## 3. Sandbox and production are separate

FreeAgent runs sandbox and production as fully separate environments, and they are not interchangeable:

| | Sandbox | Production |
|---|---|---|
| API base URL | `https://api.sandbox.freeagent.com/v2` | `https://api.freeagent.com/v2` |
| Authorization endpoint | `https://api.sandbox.freeagent.com/v2/approve_app` | `https://api.freeagent.com/v2/approve_app` |
| Token endpoint | `https://api.sandbox.freeagent.com/v2/token_endpoint` | `https://api.freeagent.com/v2/token_endpoint` |
| Credentials | sandbox app's OAuth identifier and secret | production app's OAuth identifier and secret |

You choose the environment yourself, in the same [FreeAgent connector settings](https://platform.apideck.com/configuration/accounting/freeagent) where you pasted the credentials. The **Server URL** setting defaults to production, so nothing switches to sandbox on your behalf:

- Testing with a sandbox app's credentials: select **Server URL** > **Sandbox API** (`https://api.sandbox.freeagent.com/v2`).
- Serving live consumers: select **Server URL** > **Production API** (`https://api.freeagent.com/v2`).

Keep the credential pair and the Server URL matched. Using a sandbox pair against a production company (or the reverse) fails at the authorization step, so when you promote your integration do both at once: paste the production app's OAuth identifier and secret into the connector settings **and** switch Server URL back to Production API.

## 4. Token lifecycle

Once a consumer authorizes, Apideck manages the tokens for you. What is worth knowing while you build:

- An **authorization code expires after 15 minutes**. A consumer who opens the FreeAgent approval screen and finishes much later simply restarts the connection flow.
- An **access token is valid for one hour**.
- The **refresh token is long-lived** and does not expire in normal operation, so a connection keeps working without asking the consumer to re-authorize.
- **Apideck refreshes access tokens automatically.** You do not store, rotate, or refresh tokens yourself.
- FreeAgent allows **15 token refreshes per minute per authorizing user**, which is ample for normal use but worth remembering if you script bulk re-authorization across many test connections.

## 5. Test your setup

1. Connect a FreeAgent company through [Vault](https://platform.apideck.com/vault) with a test consumer.
2. Call an accounting endpoint, for example [`invoicesAll`](https://developers.apideck.com/apis/accounting/reference#operation/invoicesAll):

```bash
curl --location --request GET 'https://unify.apideck.com/accounting/invoices' \
  --header 'x-apideck-consumer-id: test-consumer' \
  --header 'x-apideck-app-id: {APIDECK_APP_ID}' \
  --header 'x-apideck-service-id: freeagent' \
  --header 'Authorization: Bearer {APIDECK_API_KEY}' \
  --header 'Content-Type: application/json'
```

To exercise your back-off handling, FreeAgent's sandbox accepts the custom header `X-RateLimit-Test: true`, which lowers the limit to 5 requests per minute so you can observe `429` responses and the `Retry-After` header without waiting for real traffic to build up.

## FAQ and troubleshooting

**The authorization flow fails immediately with a redirect URI error.** The registered URI does not match. Confirm the app has `https://unify.apideck.com/vault/callback` exactly, on the same app whose credentials are in the Apideck connector settings.

**Authorization fails for a live company but works in sandbox.** Check both halves of the environment pair in the [connector settings](https://platform.apideck.com/configuration/accounting/freeagent): the Client ID and Client Secret must be the production app's OAuth identifier and secret, and Server URL must be set to Production API.

**The consumer approved the app but the connection did not complete.** The authorization code expired (15 minutes). Ask them to start the connection again and complete it in one sitting.

**Some records are missing for a connected company.** The connection inherits the authorizing user's FreeAgent permission level. Have a full-access user of that company authorize the connection.

**Calls return `429`.** Honour the `Retry-After` header. Limits are counted per authorizing user, so a single consumer's heavy backfill does not affect your other connections.

**Your consumers' approval screen shows "Apideck".** The connector is still using Apideck's shared credentials for testing. Complete steps 1 and 2 with your own app so your own name appears.

## Start building

Learn what else you can [build with the FreeAgent API](https://developers.apideck.com/apis/accounting/freeagent), including the supported resources and the connector's feasibility details.

Still stuck? Contact [Apideck Support](https://help.apideck.com/en/articles/7774658). Interested in a personalised demo? [Let us know](https://www.apideck.com/demo-request?from=guide).


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