Connect HelloLedger

When to use it

Use Connect HelloLedger when your app serves many businesses, for example a property management platform or an accounting firm's tool. Each user approves one company, and your server receives an ordinary developer key for it.

Building for one company you manage yourself? A key from Profile → Developers is simpler. See Quickstart.

How it works

Your app                     HelloLedger                      Your server
--------                     -----------                      -----------
"Connect HelloLedger"  --->  /connect
                             sign in or sign up
                             pick or create a company
                             approve  ------------------->  redirect_uri?code=...&state=...
                                                             POST /v1/oauth/token
                                                             <--- access_token (hl_live_ key)
                                                             call /v1 with Bearer access_token

Before you start

• Ask HelloLedger to register your app. You get an invite to Partner settings in HelloLedger (/app/partner).
• On Partner settings, add the exact redirect URIs you will use (https, or a local http address while testing) and turn on Connect. You get a client_id (starts with hlp_) and a client secret (starts with hlps_), shown once. Keep the secret on your server.
• Partner apps get a fixed set of scopes, usually the receivables template: companies:read, coa:read, reports:read, items:read, customers:write, invoices:write, payments:write.

export HL_CLIENT_ID=hlp_your-app_…
export HL_CLIENT_SECRET=YOUR_CLIENT_SECRET

1. Send the user to HelloLedger

Open this URL in the browser (a new tab or a redirect). state is a random value you generate and store in the user's session; you check it when they come back.

https://helloledger.ai/connect?client_id=hlp_your-app_…&redirect_uri=https%3A%2F%2Fyour-app.example.com%2Fhelloledger%2Fcallback&state=RANDOM_VALUE

2. The user approves

• The user signs in, or creates a HelloLedger account.
• They pick a company, or create one. New companies from Connect start with a property management chart of accounts.
• Only a company admin or accountant can approve. They see your app's name and what it will be able to do.

3. Handle the callback

HelloLedger redirects to your redirect_uri. Check that state matches what you stored, then exchange the code on your server. If the user cancels, you get error=access_denied instead of a code.

https://your-app.example.com/helloledger/callback?code=hlc_…&state=RANDOM_VALUE

https://your-app.example.com/helloledger/callback?error=access_denied&state=RANDOM_VALUE

4. Exchange the code for a key

Codes expire after 10 minutes and work once. redirect_uri must be the same value you sent in step 1. Sign the request with your client ID and secret (HTTP Basic).

billing is optional: partner means your company pays HelloLedger for this business (see Partner companies); self, the default, means the business pays for its own subscription.

curl -X POST "https://api.helloledger.ai/v1/oauth/token" \
  -u "$HL_CLIENT_ID:$HL_CLIENT_SECRET" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=hlc_…" \
  --data-urlencode "redirect_uri=https://your-app.example.com/helloledger/callback" \
  --data-urlencode "billing=partner"

{
  "access_token": "hl_live_…",
  "token_type": "bearer",
  "company_id": 1234,
  "company_name": "Maple Rentals LLC",
  "scopes": ["companies:read", "coa:read", "reports:read", "items:read", "customers:write", "invoices:write", "payments:write"],
  "partner_billing": "partner"
}

5. Use the key

Store access_token encrypted, next to the company_id, and send it as a Bearer key. It works exactly like a key created in Profile → Developers: same endpoints, scopes, limits, and errors. It doesn't expire.

All keys from your app use your app's integration name, so records you send stay matched by external ID even after the user reconnects.

curl "https://api.helloledger.ai/v1/whoami" \
  -H "Authorization: Bearer $HL_API_KEY"

Reconnecting and disconnecting

• Running Connect again for the same company issues a new key and revokes the previous one.
• The user can revoke the key anytime in Profile → Developers, where it shows as Connected via your app. Your next call returns 401 unauthorized; ask the user to connect again.
• A company can be billed by only one partner at a time.

Errors