# Advisor firms (accounting firms)

An advisor firm connection is a connected-app grant that an admin of an
accounting firm approves for the whole firm. With it your app reads the firm's
client list and delivers data about those clients. It never reaches a client's
books: every company endpoint refuses a firm token, as described in
[Choose your integration](/guides/choose-your-integration).

The connection uses the [Connected Apps](/guides/connected-apps) flow
(authorization code with PKCE) and the same authorize URL, token endpoint and
refresh rules. What differs is the scopes, the person who approves, and the
endpoints the token reaches.

## Registration

Only a connected app that LedgerBee registers can be connected to a firm; an
app that registered itself through
[Dynamic Client Registration](/guides/authentication) cannot. When you email
[development@ledgerbee.com](mailto:development@ledgerbee.com) to register, ask
for the app to connect to advisor firms and list the advisor scopes it needs.
An app can be registered for companies, for advisor firms, or for both.

## Scopes

| Scope | Allows |
|---|---|
| `advisor-clients-read` | Listing the firm's clients with `GET /v1/advisor/clients` |
| `advisor-authority-extracts-write` | Delivering tax-authority data about the firm's clients with `POST /v1/advisor/authority-extracts` |

These scopes are granted only to a firm. A company consent never carries them,
and an API key cannot hold them.

## Endpoints

<div className="lb-fixed-table">

| Endpoint | Scope | Guide |
|---|---|---|
| `GET https://api.ledgerbee.com/api/v1/advisor/clients` | `advisor-clients-read` | [The firm's clients](/guides/advisor-firms/clients) |
| `POST https://api.ledgerbee.com/api/v1/advisor/authority-extracts` | `advisor-authority-extracts-write` | [Delivering tax data](/guides/advisor-firms/authority-extracts) |

</div>

Both are listed in the [API Reference](/api) with a **Credential** line naming
an advisor firm.

## Who approves

An admin of the firm approves the connection. A member without the admin role
cannot connect a firm. The consent flow is described in
[Consent for a firm](/guides/advisor-firms/consent).

A firm holds one live connection per app. When an admin approves again, the
existing connection is renewed rather than a second one added.

## How a connection ends

| Event | Your next API call | Your next refresh |
|---|---|---|
| A firm admin disconnects your app under **Firm settings → Connected apps** in the firm's LedgerBee advisor area | `401`, `details.reason: "grant_revoked"` | `400 invalid_grant` |
| The admin who approved loses the admin role, is deactivated, or is removed from the firm | `401`, `details.reason: "grant_revoked"` | `400 invalid_grant` |
| The admin who approved deletes their LedgerBee account | `401`, `details.reason: "grant_revoked"` | `400 invalid_grant` |
| The firm is deactivated | `401`, `details.reason: "consenting_user_inactive"` | `400 invalid_grant` |
| Your app goes 30 days without refreshing | — | `400 invalid_grant` |

Each `401` carries a `WWW-Authenticate` header with `error="invalid_token"`.
To reconnect, send a current firm admin through the authorize flow again.