Copy page

Advisor firms

Consent for a firm

A firm connection starts at the same authorize URL as a company connection. The scopes you request decide what the consent screen offers, and the person approving decides whether the grant goes to a company or to their advisor firm.

Authorize

Request the advisor scopes your app is registered for:

Code
GET https://api.ledgerbee.com/auth/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &state=RANDOM_STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &scope=advisor-clients-read%20advisor-authority-extracts-write

Wrapped for readability; every parameter belongs on one query string. The parameters are the ones described in Connected Apps.

An app registered for both companies and advisor firms can name scopes of both families in one request, so one link serves either kind of customer:

Code
&scope=customers-read%20authority-extracts-write%20advisor-clients-read%20advisor-authority-extracts-write

Request only scopes LedgerBee registered for your app: any other scope, whatever its family, is refused with error=invalid_scope. Of the registered scopes, those of a family your app is not registered to connect for are dropped from the request. When every requested scope belongs to such a family, /authorize redirects with error=invalid_scope.

Consent steps

1. The user signs in to LedgerBee if they are not signed in already.
2. When the request names scopes of both families and the user can connect either a company or a firm, the screen asks What do you want to connect? with the choices A company and Your advisor firm.
3. Choosing the firm shows the firms the user administers. A user who administers more than one picks the firm; one who administers a single firm goes straight on.
4. The user approves or denies the advisor scopes.

A user who administers no firm cannot connect one. When the request names advisor scopes only, the screen tells them that only an advisor firm admin can connect the app.

By default the user approves the requested advisor scopes as a fixed list. When LedgerBee registered your app to let the user untick scopes, the grant can hold fewer than you requested.

Approval redirects to your redirect_uri with code and state; denial redirects with error=access_denied.

Token

Exchange the code and refresh exactly as described in Connected Apps. The scope in the token response holds only the scopes of the kind the user chose, and holder names the firm:

Code
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "lb_app_refresh_...",
  "scope": "advisor-clients-read advisor-authority-extracts-write",
  "holder": {
    "kind": "advisor",
    "id": "0198F2C4-5D6E-7F80-9A1B-2C3D4E5F6071",
    "name": "Example Revision ApS"
  }
}

holder.id is the firm's id and stays the same across reconnections, so your app can match a new connection to a firm it already knows. holder.name is the firm's current name, in every exchange and refresh response. The firm's own endpoints do not name the firm, so read it here.

Scopes starting with advisor- mean the token acts for the firm. Send it as a Bearer token to the firm's endpoints. Every company endpoint refuses it; see Choose your integration.

A firm holds one live connection per app. When an admin approves your app for a firm that already has one, that connection is renewed and from then on rests on this admin's consent.

Errors

These reach your redirect_uri:

Condition	What you observe	Fix
A scope outside the set registered for your app, including a name LedgerBee does not know	error=invalid_scope, error_description: Scope not declared by this app: …	Check the spelling against the scope table; request only registered scopes, or email us to add one
Every requested scope is registered for your app but belongs to a family it is not registered to connect for	error=invalid_scope, error_description starting This app is not registered to connect for the kind of holder these scopes belong to	Ask LedgerBee to register the app for advisor firms
The user denies	error=access_denied	Nothing to fix

The consent screen reports these to the user approving. Your app receives no redirect until the user approves or denies:

Condition	Status and code
The user stopped being an admin of the chosen firm after the screen loaded	403
The approval named both a company and a firm	400 CONNECTED_APP_ONE_HOLDER_ONLY
The approval named a scope outside the advisor scopes	403 CONNECTED_APP_SCOPE_BEYOND_USER_ACCESS, with details.scopes
The user chose a company but none is selected	400 CONNECTED_APP_COMPANY_REQUIRED