Sage Business Cloud Accounting – Configuration Guide
Take control of your business finances with Sage Business Cloud Accounting software. Find out about our online business solution for managing cash flow.
How to create an OAuth app in Sage Business Cloud Accounting
This guide is for the application owner: the team that builds the integration and configures the Sage Business Cloud Accounting connector once, for all of its consumers.
You can complete every step here yourself: registering on the Sage Developer Portal is self-service, with no gatekeeper to wait on before you start. Apideck's own credentials let you evaluate and test the connector immediately, and going live means registering your own Sage app so that your consumers authorise your brand rather than ours. That is what the steps below cover.
Before you start, you'll need: an account on the Sage Developer Portal, and access to the Apideck Dashboard for this connector.
1. Create your developer account and register your app
- Sign up at developer.sage.com.
- Follow Sage's Set up the basics quick start to create an application.
- Give the app the name, description and logo your consumers should see on Sage's consent screen. This is the branding they will recognise when they connect.
2. Find your Client ID and Client Secret
Sage issues a Client ID and a Client Secret for the app you just created. Copy both, and store the secret in your own secret manager as well: treat it like a password rather than something you can look up again later.
You will paste both values into the Apideck Dashboard in step 5.
3. Set the redirect URL
Set your app's redirect (callback) URL to exactly:
https://unify.apideck.com/vault/callback
This is the only redirect URL the connector uses. Apideck receives Sage's authorisation response here and exchanges it for tokens on your behalf. A redirect URL that does not match this value character for character will make Sage reject the authorisation attempt.
4. Request account authorization from Sage
Registering the app is not by itself enough to call the live API. From your app in the developer portal, submit Sage's account authorization request for it. Sage reviews and confirms this manually, and states that confirmation takes 3 to 5 working days, so submit it before the week you plan to go live rather than on the day.
While you wait, you can keep building: the connector, the unified API and your own code path are all testable ahead of the confirmation.
Do not confuse this request with a Sage Marketplace listing. The account authorization above is required to call the live API; a Marketplace listing is a separate, optional distribution step, and the Overview links to where you apply for one.
5. Add the credentials in the Apideck Dashboard
Open the Apideck Sage Business Cloud Accounting connector settings, enable Use your own client credentials, and paste in the Client ID and Client Secret from step 2. Save.
Scopes
There is nothing to select. Sage Business Cloud Accounting exposes a single scope, full_access,
which the connector requests for you. There is no granular scope list to narrow down, so plan your
consumer-facing consent copy around one all-or-nothing permission grant.
Connection settings your consumers will meet
The five steps above all happen once, in Sage's portal and the Apideck Dashboard. The two settings below are different: they live on each individual connection and are chosen per consumer, either by you during setup or by the consumer when they connect. Both must hold a value before a connection works, so build them into your onboarding rather than treating them as optional extras.
Country
Select country is a required connection setting, and it must be set before authorisation: the connector sends it as a parameter on its single authorisation URL, which is what routes the consumer to the right regional Sage sign-in.
The dropdown currently lists seven countries, but only three of them authenticate against this connector:
| Works | Does not authenticate |
|---|---|
| 🇨🇦 Canada, 🇬🇧 United Kingdom, 🇮🇪 Ireland | France, Germany, Spain, United States |
Sage Business Cloud Accounting does have regions beyond these three, but they run on Sage's older regional v3.0 API. This connector targets the Global Accounting Core API v3.1, which Sage documents as serving the United Kingdom, Ireland and Canada. Steer your consumers to Canada, the United Kingdom or Ireland in your own onboarding copy: a consumer who picks one of the other four will not get past Sage's sign-in screen.
Default Company
The Sage Business Cloud Accounting API supports multi-business: one Sage login can have access to
more than one business, so every request has to say which business it is for. Sage uses an
X-Business header for this.
The connector exposes a Default Company setting (business_id) whose options are loaded live
from the businesses the authorised login can see. Apideck then sends the selected business as the
X-Business header on every request. You can override it per request by sending an
x-apideck-company-id header, which takes precedence over the connection's setting — useful when
one consumer's login legitimately spans several businesses.
Two reasons it always has to be set:
- The setting is required on every connection, not only on logins that can see several businesses. While it is empty the connector treats the connection as incomplete, so it never becomes usable — build your onboarding so nobody stops at "connected" and assumes they are done.
- Sage's own fallback, when no
X-Businessheader is sent, targets the user's lead business — the first business that user created, which changes if that business is deleted. That can be the wrong set of books, and which business is the lead one is not under your control. Sage returns anX-Businessresponse header on every response except/businessesand/user, so the business a request actually applied to is always visible.
Sage documents the header and the lead-business fallback under Multi Business.
Reference: OAuth and API endpoints
Useful if you need to allow-list hosts or fill in a security questionnaire. Apideck performs all of these calls for you.
| Purpose | Endpoint |
|---|---|
| Authorisation | https://www.sageone.com/oauth2/auth/central |
| Token and refresh | https://oauth.accounting.sage.com/token |
| Revoke | https://oauth.accounting.sage.com/revoke |
| API base URL | https://api.accounting.sage.com/v3.1 |
Token and revoke requests are sent as application/x-www-form-urlencoded. There is one API base URL
for every supported country. Apideck refreshes access and refresh tokens automatically for as long
as the connection stays in use.
FAQ and troubleshooting
400 with error=invalid_client from the token endpoint. The app credentials are wrong. Re-copy
the Client ID and Secret from the Sage Developer Portal into the Apideck Dashboard, and check you
have not pasted a trailing space.
400 with error=invalid_grant from the token endpoint. The authorisation code or refresh token
has expired or was already used. Have the consumer reconnect to start a fresh authorisation.
A connection authorises but never becomes usable. Check Default Company first — see the section above. The connector treats a connection with that setting empty as incomplete, on single-business logins as much as multi-business ones.
Every request returns 403 Forbidden. The Sage user who authorised the connection does not have
permission to authorise applications. The connection needs re-authorising by the Sage account holder
or by a user who holds that permission.
Authorisation fails before the consumer reaches the consent screen. Check the country setting (see Country above) and the redirect URL (step 3) first: those are the two settings Sage validates before it will show a consent screen.
429 Too Many Requests. Sage applies its rate limits per app, so all of your consumers share
your app's budget (the limits themselves are listed on the connector's Overview). If your volume
genuinely needs more headroom, Sage takes increase requests at sbc-accounting-api-developers@sage.com.
Still stuck? Contact Apideck Support.