Skip to main content
Every request to the Ledger API carries a secret API key. The key identifies your workspace, chooses the environment, and limits what the request may do. Ledger has no publishable keys: every key is secret and belongs on your server.

​
Key types

A key works only in its own environment. A Sandbox key can’t read or change Live data, and the reverse.

​
Create a key

1

Open API keys

In the dashboard, choose the environment with the switch at the top of the sidebar, then open Settings › API keys.
2

Name it after what will use it

Choose Create key and name the service or deployment that will hold it, such as “Production backend”. Names are unique per environment.
3

Choose its permissions

Leave Restricted mode off for full access, or turn it on and choose None, Read or Write for each group below.
4

Copy it once

Ledger shows the key once and stores only a hash of it. Put it in your secret manager or environment, such as LEDGER_API_KEY.
Each environment holds up to 8 keys. Create a new key before revoking an old one so you can rotate without downtime: existing keys keep working until revoked, and a revoked key stops working immediately.

​
Authenticate requests

Send the key as a bearer token:
A missing, unknown or revoked key returns 401:
Response (401)

​
Permissions

A restricted key has a level for each of four groups. Read grants the read scope; Write grants both. A request that the key isn’t allowed to make returns the same 401 unauthorized as an invalid key.

​
Suggested keys

​
Keep keys safe

  • Server only. Never put a key in a browser, mobile app or public repository. Anyone with it can spend your customers’ credits.
  • One key per service. If one leaks, you revoke one key, not your whole integration.
  • Restrict by default. Give each service only the groups it calls.
  • Rotate on suspicion. Create a replacement, deploy it, then revoke the old key in Settings › API keys.
Ledger never logs API keys. Its request logs record the key’s ID instead.

​
Next steps

Errors

The error shape and every code.

Sandbox and Live

What each environment holds.