Onboarding

The self-serve journey from sign-up to your first product call — register, get entitled, open a context, provision, and go.

Onboarding takes you from nothing to your first authenticated product call. The whole journey is self-serve for the products that allow it; payment rails require an operator approval step, called out below.

There are two entry points: POST /partners registers an identity and returns your credentials; POST /onboard does register, entitlement selection, and self-serve provisioning in a single call. Use /onboard to start fast.

The journey

Register

Call POST /partners (or POST /onboard). You receive two credentials — a JWT on-ramp and a durable HMAC root — both resolving the same partner identity. Each secret is shown once; store both securely.

Authenticate

Sign your next request with either credential. See Authentication for the canonical string. The HMAC root is your durable, non-expiring path.

Get entitled

Your entitlement set is the products you're enabled for. Self-serve products (for example, the ledger) are enabled immediately. Approval-required products — the payment rails — are recorded as pending until an operator approves them.

Open a context

Each of your customers is a context you thread. Create one with POST /contexts. A context maps to that customer's downstream product tenant — see Contexts.

Provision into a product

Call POST /products/{product}/provision for the selected context. The gateway holds the product's privileged service key and provisions on your behalf, returning the product's own credential once. You then authenticate to the product directly.

Make your first call

Reach the product through Passthrough. The gateway threads the product's credential; you sign only your One-API leg.

Payment rails need approval

A cold /onboard call that requests a payment rail does not create a live rail partner. The rail is recorded pending and becomes reachable only after an operator approves it. The response's pending array names what's awaiting approval.

Choose your products

You enable exactly the products you want — each is independent, and you integrate only the ones you use. A wallet, VAS, and ledger integration is complete on its own; nothing outside the bank rail depends on the bank rail.

Self-serve — provisioned immediately on basic verification:

Wallet — customer-owned stored-value accounts. See Wallet.
VAS — airtime, data, bills, and gift / reward redemption. See VAS.
Ledger — your own double-entry book. See Ledger.

Approval-required — the licensed bank rail, optional:

Bankrail Gateway — the licensed collection and payout rail. Requires operator approval (real rail, full KYC) and is recorded pending until approved. You only need it if you want licensed bank collections or payouts. See Bankrail Gateway.

Onboard with just the products you want — e.g. ["wallet", "vending", "ledger"] — and they provision immediately, self-serve, with no bank-rail involvement. Add the bank rail later if you ever need it; it never blocks the self-serve products.

The no-lockout guarantee

Because you hold the durable HMAC root from the moment you register, an expired JWT on-ramp is never a lockout — re-mint a fresh JWT by authenticating with the root.

Contexts — serve many customers without re-integrating.
Provisioning — the trusted-service key model.