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

A FreeAgent Developer account (free) to create apps and read their credentials: dev.freeagent.com/signup.
A FreeAgent company to test against. For development, create a free sandbox company at 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.
An Apideck account with access to the FreeAgent connector settings 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.

Sign in to the FreeAgent Developer Dashboard and open My Apps.
Select Create New App.
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.
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.
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 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.

Open your app in the Developer Dashboard and copy the OAuth identifier and OAuth secret.
In the Apideck Dashboard, open the FreeAgent connector settings (Configuration > Accounting > FreeAgent).
Select Use your own client credentials and paste the OAuth identifier as the Client ID and the OAuth secret as the Client Secret.
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 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

Connect a FreeAgent company through Vault with a test consumer.
Call an accounting endpoint, for example invoicesAll:


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: 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, including the supported resources and the connector's feasibility details.

Still stuck? Contact Apideck Support. Interested in a personalised demo? Let us know.