Authentication
API apps, key types, restricted keys, and rotation.
API Apps
Watenga uses API apps to manage your keys. Each app has a Client ID and a Secret Key.
You can create multiple apps — one for your website, one for your mobile app, one for WHMCS, etc. Each has independent keys and webhook configuration.
Create and manage apps in the Developer Console at https://developer.watenga.africa/apps.
Key Types
| Key | Use | Exposure |
|---|---|---|
Client ID (pk_live_ or pk_test_) | Browser / frontend (Watenga.js) | Safe to expose publicly |
Secret Key (sk_live_ or sk_test_) | Server-side API only | Never expose — full account access |
Restricted Key (rk_live_ or rk_test_) | Limited integrations | Scoped permissions only |
Public key — Watenga.js and the mobile sheets. A publishable key only pays what your server decided: a checkout session's client_secret (from POST /v1/checkout/sessions with your secret key), a payment link or an invoice.
const w = Watenga('pk_test_abc123...');
w.mount('#pay', { clientSecret: session.client_secret, amount: 25, currency: 'USD', reference: 'INV-001' });Secret key — server-side API call:
Authorization: Bearer sk_test_abc123...Never expose your Secret Key
Restricted Keys
Give a system only the access it needs: a restricted key (rk_test_…, rk_live_…) holds one scope per resource, each none, read (GET) or write (everything). Create them in the developer console under your API app (two-step verification); a key can expire on a date you choose.
| Scope | What it reaches |
|---|---|
| transactions | Checkout and checkout sessions, payments, saved cards, disputes, splits, TrustPay |
| refunds | Refunds (write: refund, within the key’s own per-currency limits) |
| payment_links | Payment links |
| invoices | Invoices and quotations |
| subscriptions | Plans, subscriptions, usage and entitlements |
| customers | Customers |
| shop | Stores, products and orders |
| donations | Donation campaigns and gifts |
| bookings | Booking services and appointments |
| elements | Secure Elements sessions |
| account | Balance, profile, subaccounts, bank accounts |
| webhooks | Webhook endpoints, listen sessions and trigger |
A route no scope covers is refused with 403 SCOPE_FORBIDDEN: use a secret key for it. Payouts and disbursements are dashboard-only, with two-step verification, and no key reaches them.
Ask the API what the key in use may do:
curl https://api.watenga.africa/v1/account/api-key -H "Authorization: Bearer rk_test_..."
# { "kind": "restricted", "livemode": false, "scopes": { "transactions": "read", "refunds": "none", ... }, "features": { ... } }Key Rotation
Rotate a secret key in the developer console (your app → Credentials → Rotate secret, two-step verification). If the key may have leaked, end the old key at once. Otherwise keep it working for an overlap (1 hour to 7 days) while your servers move to the new key; the console shows when it stops and lets you stop it early.