API keys
When you need one
Only when something works with the ledger without a signed-in user:
- another system integrating against the Ledger17 APIs — an invoicing system posting sales, a payroll run posting salaries, a bank feed posting settlements
- an AI agent running unattended, with nobody present to approve a login
When a person uses Ledger17 — or an assistant works on behalf of a signed-in person — no API key is involved: the person’s own login is the credential.
One key, one tenant
An API key is bound to one tenant. That keeps integrations simple: a key never has
to choose which organization it acts in, the way a user with several memberships must.
The tenant resolved from the key is what the APIs enforce — the X-Tenant-ID header
must match it.
Scope it to what it needs
A key carries exactly the permissions
you grant it, in the same {orgId}:{action}:{resource} model as user logins. Give it
only what the integration actually uses:
| Integration | Sufficient grant |
|---|---|
| A dashboard reading balances | read:ledger |
| A system posting transactions | write:ledger |
| A sync of customers and suppliers | write:registry |
The APIs are the authority on what a token may do — a key’s permissions are enforced
on every call, exactly as for users, and a missing permission answers 403 naming the
grant that was required.
Where keys are managed
API keys are created, scoped and revoked in the Ledger17 admin console at admin.ledger17.com — the same place you manage your tenant and subscription. Sign up at admin.ledger17.com/signup.
The key is a client credential: your integration exchanges it for a short-lived bearer token and sends that token on every request, as described in Authentication. Treat the key like a password — store it in a secret manager, and revoke it from the console if it leaks.
Next
- Authentication — how the token is used on the wire
- AI agents — connecting an unattended assistant via MCP