Skip to main content
Nucleus employs a defense-in-depth authentication model structured around three operational tiers:
  1. Digital Banking & Mobile / Web Apps (Self-Service APIs)
  2. Partner APIs, Payment Gateways & Switches (API Key Authentication)
  3. Developer Documentation & Architecture Portals (Portal Keys)

​
1. Required Headers on Every Request

Every REST request directed at the core banking engine must identify its target tenant:
If you cannot pass headers (e.g. testing directly via browser or webhooks), you can pass ?tenantIdentifier={tenantSlug} as a query parameter.

​
2. Digital Banking & Self-Service Token Auth

When building proprietary Mobile Apps (iOS/Android) or Web Banking Portals for your customers, end-users do not use API keys. Instead, they authenticate via credential exchange to receive an ephemeral session token:
The response returns a base64EncodedAuthenticationKey:
Subsequent requests from the mobile app attach this key in the Authorization header:
All endpoints prefixed with /nucleus/api/v1/self/* automatically constrain queries to the accounts linked to that authenticated user. Customers can never access or tamper with data belonging to other accounts.

​
3. Partner Services & Payment Rail API Keys

For backend server-to-server integrations (such as NIP instant payment aggregators, card issuing processors, credit bureaus, or external fintech partners), Nucleus supports scoped API keys:

​
Key Generation & Rotation

  • API Keys are generated inside the Bank Admin Console under Settings →\rightarrow Integrations.
  • Keys are cryptographically hashed using SHA-256 before storage in c_external_service_properties.
  • Keys can be scoped to specific permissions (e.g. TRANSFERS_READ, TRANSFERS_CREATE) and can be rotated without server restart.

​
4. Documentation & Developer Portal Keys

When developers visit the interactive API documentation and gated architecture runbooks:
  • What key is used? The Documentation Portal Key (pk_...).
  • Where is it issued? In the Core Banking Administrator Portal under the institution’s settings page (POST /api/v1/portal-key).
  • How is it used? Engineers enter their bank’s deploymentId (e.g. pilot-mfb) and apiKey (pk_7d89ab12...) to unlock:
    • High-availability deployment manifests
    • Disaster recovery (DR) playbooks
    • Sandbox test API credentials
    • Regulatory submission runbooks

​
5. Webhook Signatures (HMAC-SHA256)

When Nucleus dispatches asynchronous webhook events (e.g. incoming NIP transfer settled, loan disbursed), it includes a cryptographic signature:
To verify the payload in your application:
  1. Extract the timestamp t and signature v1 from the header.
  2. Compute HMAC_SHA256(timestamp + "." + rawBody, webhookSecret).
  3. Compare your calculated hash against v1 using constant-time comparison.