Get started

    Authentication

    Send your key as a Bearer token. Keys are limited to the companies and scopes you choose.

    Bearer keys

    Send the secret in the Authorization header on every request. Keys start with hl_live_.

    Older keys may still use HTTP Basic with client_id as the username and the secret as the password. New keys should use Bearer. The customers, invoices, payments, items, vendors, bills, and expenses endpoints accept only Bearer and return 401 bearer_required for Basic.

    text
    Authorization: Bearer hl_live_…

    What a key can reach

    • Companies: only the companies chosen when the key was created. Other company IDs return 403 forbidden_company.
    • Scopes: each route needs one scope. A missing scope returns 403 insufficient_scope.
    • Records: writes are matched by your integration name (or the key's client_id when no integration is set), so two partner apps can't overwrite each other's records.

    Expiry, rotation, and revocation

    • Developer keys never expire unless you choose 30, 90, or 180 days or 1 year. AI assistant keys expire after one year by default. You can change a key's expiry later without a new secret.
    • Rotating issues a new secret and keeps the key's expiry setting. The previous secret keeps working for 24 hours so you can deploy the new one.
    • Revoking stops the key immediately.
    • The key's owner gets an email whenever it is created, rotated, changed, or revoked.

    Allowed IPs (optional)

    Limit a key to your servers' addresses or CIDR ranges (up to 20). Calls from anywhere else return 403 ip_not_allowed, so a stolen secret is useless outside your network.

    GET /v1/whoami returns client_ip, the address HelloLedger sees for your server. Leave the list empty if your host's outbound address changes, as on many serverless platforms.

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

    Keeping the secret safe

    • Store it in your server's secret manager or environment, never in source control.
    • Never send it to a browser or mobile app. Call HelloLedger from your backend.
    • If a secret leaks, rotate or revoke it in Profile → Developers right away.
    • Keys start with hl_live_ so secret scanners can recognize them.