Authentication
API keys, scopes, and the things a key deliberately cannot do.
Send your key as a bearer token:
curl https://sandbox.inversepay.app/api/b/v1/charges \
-H "Authorization: Bearer $INVERSEPAY_TEST_KEY"Two kinds of credential
A dashboard session is a person acting in a role. An API key is your business's own authority, narrowed to a set of scopes.
They are not the same thing, and we do not pretend otherwise. A key has no seat on your team, so anything that needs a person accountable for it is closed to keys entirely — however the key is scoped.
Modes
A key carries a mode and it is in the key itself: sk_test_ is test,
sk_live_ is live. Mode is never taken from the request — a header saying
"treat this as test" would be a way to write test data with a live key and, far
worse, a way to have a live payment treated as simulated.
A dashboard session carries no mode, and a credential with no mode is live. That is the only safe default for an unmarked credential, and it is worth knowing before you go looking for a payout you raised: payouts are raised by a session, so they are live rows, and a test key cannot see them.
Scopes
| Scope | Grants |
|---|---|
payments:read | read charges, payment links, invoices, refunds, virtual accounts |
payments:write | create charges |
payouts:read | read payouts, batches and schedules |
balances:read | statements and FX rates |
webhooks:manage | manage endpoints and read deliveries |
A missing scope is a 403, and the message names the scope you need.
payouts:write is a test-mode scope. A key holding it can create a payout
in test mode, which is how you rehearse a decline or a timeout without a person
in the loop. It grants nothing in live: raising real money stays a session's
act, however the key is scoped.
What a key can never do
Not "is not scoped for" — cannot, at all:
- invite or manage members, or change roles
- create, revoke or regenerate another API key
- create, cancel or approve a payout
- issue a refund, or execute an FX conversion
- submit KYB documents or change business settings
Two reasons. Governance is a person's act and needs a person accountable for it. And a key that can mint keys cannot be contained by revoking it — the first thing anybody who steals one does is issue another.
Payouts read through a key; they are raised in the dashboard.
Beneficiaries, payroll, bill payments, batch and schedule management, report exports and card operations are closed to keys for the same reason — each one either moves money or decides who may be paid.
Idempotency, twice
Two separate mechanisms share a name, and knowing which is which saves an afternoon.
The Idempotency-Key header is honoured on every POST, PUT and PATCH
under /api/b/v1. The first request's response is stored and replayed for
24 hours, with Idempotent-Replay: true on the replay. It is fingerprinted
against the body, so reusing a key with a different body is a 422
(IDEMPOTENCY_KEY_REUSED), and repeating one while the first is still running is
a 409 (IDEMPOTENCY_KEY_IN_FLIGHT). A 5xx releases the key rather than
pinning it to a non-outcome, so the one request you never got an answer for is
the one you can always retry.
The idempotency_key field in the body of a charge or a payout is the
domain's own. It deduplicates the object: send it again and you get the
original charge or payout back. It is scoped to your business, and on a charge to
your mode as well — so the order references you use while building cannot collide
with the real ones later.
Send both. The header protects the request, the field protects the money.
Rotation
Regenerating a key returns a new secret and keeps the old one working for an overlap window, so you can deploy the new secret without a synchronised restart. Revoke the old one when your last instance has it.