Authentication overview

The Horus Software API uses OAuth 2 with the authorization code grant. A Horus user grants your integration access to the data available through their account, without ever sharing their password with you.

Once the flow is complete, every API call is authenticated with a Bearer access token:

Authorization: Bearer ACCESS_TOKEN

One API URL per license

Each fiduciary or SMB using Horus Office has its own database, hosted at its own location. As a consequence, each license has its own API URL. This shapes the whole flow:

1. The authorization flow always starts on the central Horus portal: https://my-horus.com/fr/api (or https://my-horus.com/nl/api).
2. During the flow, the user selects the license they want to connect.
3. At the end of the flow, your application receives the selected license's base URL in the api_url parameter.
4. From then on, every request goes to that api_url: the token exchange, token refreshes and all API calls.

 Your application ──(1) authorization request────────▶ my-horus.com
                  ◀─(2) code + api_url ──────────────── (login + license selection)

 Your application ──(3) token exchange, API calls ───▶ api_url of the selected license

🚧

Never hard-code the API URL

The api_url is different for every license. Read it from the authorization redirect, store it with the connection, and use it as the base URL for every request.

In this documentation, https://api.fiduciary.example stands for "the api_url you received". It is not a real address.

Connecting several licenses

An integration can be connected to any number of licenses, for example when it serves many fiduciaries. Each connection is independent:

• the user goes through the authorization flow once per license,
• each connection has its own api_url, access token and refresh token,
• always use a license's tokens with that license's api_url.

Store these values together, as one record per connected license.

What to read next

• Authorization flow: every parameter of the authorization request, the redirect and the token exchange.
• Token lifecycle: access token expiry, refresh tokens and recommended practices.
• Prefer learning by doing? Follow the Quickstart.