API keys

API keys authenticate your server to Ledgerline. Every request must carry one, and the key decides which environment (sandbox or live) and which permissions the request runs with. Treat keys as passwords: they can move money.

Key types

Ledgerline issues two kinds of key, each in a test and a live variant.

The prefix is the quickest way to tell which environment a key belongs to. A test key can never touch live data, and a live key can never touch sandbox data.

Authenticating a request

Send the key in the Authorization header as a bearer token. Ledgerline does not accept keys in query strings, because URLs end up in logs.

curl https://api.ledgerline.dev/v1/ledgers \
  -H "Authorization: Bearer ll_live_sk_replace_me"

A missing, malformed or revoked key returns HTTP 401 with the code api_key_invalid or api_key_revoked. A valid restricted key that lacks the needed scope returns 403 with scope_missing. The full list is in Error format and codes.

Creating a key

1. Open Developers > API keys in the dashboard at https://dashboard.ledgerline.dev.
2. Choose the Test or Live tab and select Create key.
3. Pick Secret or Restricted, name the key after the service that will use it, and set an optional expiry date.
4. Copy the key. It is shown once. Ledgerline stores only a hash, so we cannot show it again.

You can also create keys with POST /v1/api_keys using a key that has full access. Creating live keys requires an approved business verification.

The number of keys per environment depends on your plan: 5 on Starter, 25 on Growth and 100 on Scale. See Limits and quotas.

Rolling a key

Roll a key on a schedule, and immediately if you suspect a leak. Rolling creates a replacement and retires the old key on a timer, so you can deploy without downtime.

curl -X POST https://api.ledgerline.dev/v1/api_keys/key_01JA3F7P/roll \
  -H "Authorization: Bearer ll_live_sk_replace_me" \
  -d expire_old_after_hours=24

By default the old key keeps working for 24 hours after a roll. You can set expire_old_after_hours anywhere from 0 to 72. Use 0 when a key is compromised: the old key stops working at once. Each roll emits an api_key.rolled event so your tooling can react.

Revoking a key

Revoking is immediate and cannot be undone. Open the key in the dashboard and choose Revoke, or call DELETE /v1/api_keys/{id}. Requests made with the key afterwards fail with api_key_revoked.

Keeping keys safe

• Store keys in a secrets manager or environment variables, never in source control, mobile apps or browser code.
• Give each service its own key so you can revoke one without an outage elsewhere.
• Prefer restricted keys for anything that does not need full access, such as a reporting job that only reads.
• Add an IP allowlist on Growth and Scale plans so a leaked key is useless from other networks.
• Set an expiry on keys you hand to contractors.

Using a key from the SDKs

Both official SDKs read LEDGERLINE_API_KEY from the environment when you do not pass a key explicitly. See Node SDK and Python SDK.