> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onnucleus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication & Keys

> Everything you need to know about API keys, session tokens, and multi-tenant security.

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:

| Header Name                 | Type   | Description                                                             |
| --------------------------- | ------ | ----------------------------------------------------------------------- |
| `Nucleus-Platform-TenantId` | String | The unique slug of the institution (e.g. `pilot-mfb`, `sterling-bank`). |
| `Content-Type`              | String | Mandatory `application/json` for all POST, PUT, and PATCH bodies.       |

<Note>
  If you cannot pass headers (e.g. testing directly via browser or webhooks), you can pass `?tenantIdentifier={tenantSlug}` as a query parameter.
</Note>

***

## 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:

```bash theme={null}
POST /nucleus/api/v1/self/authentication?tenantIdentifier=pilot-mfb
Content-Type: application/json

{
  "username": "customer_chinedu",
  "password": "CustomerPassword123!"
}
```

The response returns a `base64EncodedAuthenticationKey`:

```json theme={null}
{
  "username": "customer_chinedu",
  "userId": 104,
  "base64EncodedAuthenticationKey": "Y3VzdG9tZXJfY2hpbmVkdTpDdXN0b21lclBhc3N3b3JkMTIzIQ==",
  "authenticated": true
}
```

Subsequent requests from the mobile app attach this key in the `Authorization` header:

```bash theme={null}
Authorization: Basic Y3VzdG9tZXJfY2hpbmVkdTpDdXN0b21lclBhc3N3b3JkMTIzIQ==
Nucleus-Platform-TenantId: pilot-mfb
```

<Info>
  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.
</Info>

***

## 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:

```bash theme={null}
X-Nucleus-API-Key: live_key_9f823a10e7b44c8da123
Nucleus-Platform-TenantId: pilot-mfb
```

### 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:

```http theme={null}
X-Nucleus-Signature: t=1694512345,v1=5d41402abc4b2a76b9719d911017c592
X-Nucleus-Event: account.credit
```

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.