Authentication
Use an organisation-scoped API key from your backend. Its prefix selects the data plane and its seven-scope vocabulary limits what the integration may do.
The Sender API authenticates with an opaque bearer API key. There is no token exchange: the key is the credential.
“Bearer” describes how the key is sent in the HTTP Authorization header; it
does not mean OAuth. Do not configure an OAuth client, authorization URL, or
token URL for the Sender API.
POST /sender/v2/plans/pln_01J8ZQ4T/runs HTTP/1.1
Host: api.keepable.co
Authorization: Bearer kpk_live_aZ8mQqWRtY2I4eK7hPnLrXv...
Idempotency-Key: 9f1c8e2a-7b3d-4f10-9a2e-6c5b4d3e2f1a
Content-Type: application/jsonA key identifies its organisation. Do not put a tenant id in a path or accept one from a user.
Getting and managing a key
Create, rotate, and revoke keys in Keepable Workspace. Credential lifecycle is intentionally not part of the API-key surface: a leaked key must not be able to rotate itself, mint another key, or hide its own revocation.
Use a kpk_test_ key while building. Once your organisation is approved and
funded, mint a separate kpk_live_ key. The prefix chooses the data plane; the
host and paths stay the same.
A secret is shown only when Workspace creates or rotates the key. Store it in server-side secret storage. Never put it in a browser, mobile application, log, or distributed client.
Confirm your wiring
GET /me is available to every valid API key and touches no business state.
GET https://api.keepable.co/sender/v2/me
Authorization: Bearer {{KEEPABLE_TOKEN}}{
"organization_id": "org_01J8ZQ4T",
"organization_name": "Anchor Microfinance Bank",
"plane": "live",
"tier": "standard",
"approved": true,
"scopes": ["plans.read", "correspondence.read", "correspondence.write"]
}Scopes
The public vocabulary contains exactly seven scopes:
| Scope | Grants |
|---|---|
documents.write | Upload an input document for a plan run. |
plans.read | Discover plans and inspect their required inputs. |
correspondence.read | Reconcile plan runs, participants, and permission changes. |
correspondence.write | Run a published plan or withdraw its correspondence. |
responses.read | Read collected answers with sensitive values masked. |
responses.sensitive | Reveal sensitive answers or retrieve a submitted file. |
claims.read | Read claim codes created by tokenized delivery. |
Grant only what the integration needs. A send-only worker commonly needs
documents.write, plans.read, and correspondence.write. A reconciliation
worker adds correspondence.read. Response and claim access should be explicit
and off by default.
responses.sensitive is deliberately separate from responses.read. Reading
a masked response and disclosing somebody's BVN or identity document are
different acts. Revealing a sensitive field requires both scopes; downloading
a submitted file requires responses.sensitive.
mTLS for tier-1 senders
Tier-1 senders may be required to present a client certificate in addition to the key. Partner Engineering provisions it during onboarding. mTLS is layered on top of bearer authentication, not used instead of it.