Authentication

The Bold MFB API supports two authentication profiles. Each Business is configured server-side to use one or the other; partners do not switch profiles per request.

​

Choosing a profile

Operations configure the profile per Business at onboarding. If you are unsure which profile your tenant uses, ask Kele Operations.

​

Profile v1-static

Static credential pair. Both values are obtained from the API settings page in the Kele dashboard.

"headers": {
  "x-api-key": "pk_live_…",
  "x-api-secret": "your_secret_key"
}

The public key remains static. The secret key undergoes periodic rotation — best practice is every 30 to 90 days. The secret key cannot be recovered after the first display; copy it immediately on creation.

​

Obtaining keys

Navigate to the API settings page in the Kele dashboard and click Generate. First-time users receive a one-time public key and secret key. Subsequent rotations issue a new secret while the public key persists.

​

Profile v2-hmac

The api_secret never leaves the partner. Each request carries a SHA-256 HMAC of a canonical string that includes the timestamp, method, path, and raw body.

​

Headers

Every request must carry these three headers:

Content-Type: application/json for any request with a body.

​

Canonical signing string

{unix_seconds}.{HTTP_METHOD_UPPER}.{request_path_with_leading_slash}.{canonical_query}.{raw_request_body_or_empty}

Five dot-separated segments. Empty segments are still represented by their delimiting dots — a GET with no query and no body ends in ...

canonical_query is the request’s query parameters, sorted lexicographically by key and re-encoded with RFC-3986 percent-encoding (space as %20, not +). When there are no query parameters this segment is the empty string. The exact bytes you sign for the query must also be the exact bytes on the wire — if your HTTP client re-orders or re-encodes them, the signature will not verify.

Three things to watch for:

1. Path is the URL path component only, with the leading /api prefix included. For example, sign /api/outlets, not https://corebanking.boldmfb.com/api/outlets?status=ACTIVE and not /outlets. The query goes into its own segment, not the path.
2. Query is part of the signature. Different query parameters produce different signatures, so two GETs to the same path with different params in the same second do not collide. The replay cache is keyed on (api_key, signature) — only an exact retransmission of the same request triggers REPLAY_DETECTED.
3. Raw body is the exact bytes you transmit. If your HTTP client re-serialises the JSON in a different order between signing and sending, the signature will mismatch. For a GET with no body, the body segment is the empty string and the trailing dot is still present.

​

Reference signers

Each tab below is a complete, copy-pasteable signer that builds the canonical string, computes the HMAC, and sends the request with the three required headers. Drop it into your project, set the three env vars (KELE_BASE, KELE_API_KEY, KELE_PARTNER_SECRET), and replace the example call at the bottom with your own.

• Node.js
• TypeScript
• Python
• PHP
• Go
• C#
• Bash

const crypto = require('node:crypto');

const KELE_BASE = process.env.KELE_BASE;            // https://corebanking-staging.boldmfb.com
const API_KEY   = process.env.KELE_API_KEY;         // pk_test_…
const SECRET    = process.env.KELE_PARTNER_SECRET;  // plaintext secret minted by Kele Ops

// Sorted, RFC-3986 query string. Empty when no params.
function canonicalQuery(query) {
  if (!query) return '';
  return Object.keys(query)
    .sort()
    .map(k => `${encodeURIComponent(k)}=${encodeURIComponent(String(query[k]))}`)
    .join('&');
}

async function signedRequest(method, path, { body = null, query = null } = {}) {
  const upperMethod = method.toUpperCase();
  const rawBody     = body === null ? '' : JSON.stringify(body);
  const ts          = Math.floor(Date.now() / 1000).toString();
  const qs          = canonicalQuery(query);
  const canonical   = `${ts}.${upperMethod}.${path}.${qs}.${rawBody}`;
  const signature   = crypto.createHmac('sha256', SECRET).update(canonical).digest('hex');

  const url = KELE_BASE + path + (qs ? `?${qs}` : '');

  return fetch(url, {
    method: upperMethod,
    body: body === null ? undefined : rawBody,
    headers: {
      'Content-Type': 'application/json',
      'x-api-key':    API_KEY,
      'x-timestamp':  ts,
      'x-signature':  signature,
    },
  });
}

// Example
const res = await signedRequest('GET', '/api/wallets/balance');
console.log(res.status, await res.json());

Two things to verify in your client before you trust it end-to-end:

• The serialised body you sign is the exact bytes you transmit. Most HTTP clients will faithfully forward a string body, but middleware (proxies, logging hooks, body parsers that re-stringify) can silently re-encode JSON and break the signature.
• A repeated request with the same timestamp returns 401 REPLAY_DETECTED on the second call. If it doesn’t, your shared-state cache (Redis on our side) is misbehaving — escalate.

​

Secret rotation

Partners rotate partner_secret with a 7-day overlap window. During the overlap the server accepts both the current and the previous secret, so the partner can deploy the new secret at its own cadence within those seven days.

Rotation is initiated by Kele Operations. After rotation, you receive the new plaintext secret out-of-band; the previous one continues to sign valid requests for 7 days from partner_secret_rotated_at.

If a leaked secret needs to be killed immediately, Kele Operations performs a compromise rotation: the previous secret is not populated, so the old secret stops working the instant the new one is installed.

​

Common 401 errors

​

Environment-scoped keys (both profiles)

API keys are environment-scoped. Sandbox keys (pk_test_*) cannot be used against live, and live keys (pk_live_*) cannot be used outside production. The middleware rejects mismatched env keys before any further processing.