Dynamic Key V2

End-to-end encryption protocol that replaces the shared-secret handshake (v1). Uses ECDH P-256, HKDF-SHA256, and AES-256-GCM.

Integration flow

Required headers

Handshake — POST /api/info/v2

{
  "clientPublicKey": "BASE64_SPKI_EPHEMERAL_KEY",
  "device": {
    "id": "browser-uuid-v4",
    "platform": "browser"
  },
  "client": {
    "type": "internal",
    "clientId": "internal-web-client"
  }
}

Response

{
  "serverPublicKey": "...",
  "sessionId": "opaque-session-id",
  "token": "jwt",
  "expireToken": 0,
  "expiresAt": "2026-06-04T00:00:00.000Z"
}

Encrypted request — POST /api/request/v2

Internal plaintext describes the upstream route:

{
  "method": "GET",
  "path": "/countries/get",
  "headers": {},
  "query": {},
  "body": null
}

Sent encrypted as an envelope:

{
  "nonce": "base64-12-unique-bytes",
  "data": "base64(ciphertext || authTag)"
}

Route allowlist

Only routes explicitly allowed in the gateway can be proxied via v2:

• POST /users/login
• GET /users/getbyid/:id
• GET /qr/get/reverse/:BFP
• GET /companies/getbyid/:idCompany
• GET /countries/get, /lang/get, etc.

Web SDK — @nimbus/sdk-web

TypeScript reference client for Dynamic Key V2 in browsers. Handles handshake, session derivation, encryption, and protected requests against API Gateway v2.

v0.1.3 — published to AWS CodeArtifact as @nimbus/sdk-web

Responsibilities

• Dynamic Key V2 handshake (POST /api/info/v2)
• ECDH P-256 + HKDF-SHA256 session key derivation
• AES-256-GCM encrypt/decrypt for proxy envelopes
• Protected request client (POST /api/request/v2)
• Optional session storage adapter (NIM-944)

Install from CodeArtifact

aws codeartifact login \
  --tool npm \
  --repository nimbus-sdk-web-v2 \
  --domain nimbus \
  --domain-owner $AWS_ACCOUNT_ID

npm install @nimbus/sdk-web

Install from monorepo

cd sdk/nimbus-sdk-web-v2
npm install
npm run build

Configuration

Trailing slashes on gatewayBaseUrl are stripped automatically.

Session lifecycle

1. Reuse in-memory session when not expired.
2. Try sessionStorage.load() when an adapter is configured.
3. Perform a fresh handshake via POST /api/info/v2.
4. Persist session through sessionStorage.save() after handshake (when adapter supports it).

Basic usage

import { SecureApiClient } from '@nimbus/sdk-web';

const client = new SecureApiClient({
  gatewayBaseUrl: 'https://apiauthdev.nimbus-id.com',
  client: { type: 'internal', clientId: 'internal-web-client' },
  device: { id: 'browser-or-device-id', platform: 'browser' },
});

await client.ensureSession();

const data = await client.protectedRequest({
  request: {
    method: 'GET',
    path: '/qr/get/reverse/example-bfp',
    query: {},
    body: {},
    headers: {},
  },
});

Public API

• SecureApiClient — recommended entry point
• DynamicKeyClient — handshake only
• encryptJson / decryptJson — low-level crypto
• NimbusSdkError + SDK_ERROR — typed errors
• EncryptedSessionStorage — storage scaffold (NIM-944, persistence pending)
• createDynamicKeyV2Aad — AAD helper for v2:{sessionId}

Compatible frontend stacks

The SDK is framework-agnostic. It only requires a browser runtime with Web Crypto API and fetch.

Not supported: server-side rendering without a browser crypto.subtle context. Run the SDK in the client bundle only.

Frontend integration

1. Install @nimbus/sdk-web from CodeArtifact or build from the monorepo.
2. Wrap SecureApiClient in a framework-specific adapter (service, hook, composable).
3. Gate legacy V1 vs V2 with an environment flag (e.g. VITE_API_SECURITY_MODE).
4. Call ensureSession() on app start or before protected calls.
5. Route business API calls through protectedRequest() — never call microservice URLs directly.

Examples

Angular service

import { SecureApiClient } from '@nimbus/sdk-web';

@Injectable({ providedIn: 'root' })
export class ApiClientV2Service {
  private client = new SecureApiClient({
    gatewayBaseUrl: environment.gatewayUrl,
    client: { type: 'internal', clientId: environment.clientId },
    device: { id: this.deviceId, platform: 'browser' },
  });

  async getQrReverse(bfp: string) {
    await this.client.ensureSession();
    return this.client.protectedRequest({
      request: {
        method: 'GET',
        path: `/qr/get/reverse/${bfp}`,
        query: {},
        body: {},
        headers: {},
      },
    });
  }
}

React hook

import { useCallback, useMemo } from 'react';
import { SecureApiClient } from '@nimbus/sdk-web';

function createClient() {
  return new SecureApiClient({
    gatewayBaseUrl: import.meta.env.VITE_GATEWAY_URL,
    client: { type: 'internal', clientId: import.meta.env.VITE_CLIENT_ID },
    device: { id: getDeviceId(), platform: 'browser' },
  });
}

export function useSecureApi() {
  const client = useMemo(() => createClient(), []);

  const getQrReverse = useCallback(async (bfp: string) => {
    await client.ensureSession();
    return client.protectedRequest({
      request: {
        method: 'GET',
        path: `/qr/get/reverse/${bfp}`,
        query: {},
        body: {},
        headers: {},
      },
    });
  }, [client]);

  return { getQrReverse };
}

Security considerations

• Do not persist ephemeral ECDH private keys across page reloads.
• Rotate the session on logout or when expiresAt is reached.
• Use a unique nonce per request — the SDK handles this per call.
• Do not log tokens, session keys, or envelopes in production.

Local smoke test

Start API Gateway V2 locally, then run:

cd sdk/nimbus-sdk-web-v2
GATEWAY_URL=https://localhost:3072 npm run smoke:local

Related documentation

• qa/sdk-web-v2.md — integration reference
• qa/dynamic-key-v2.md — protocol QA cases
• contracts/api-gateway-v2.yaml — wire contract

Mobile Guide (iOS / Android)

Native app flow with QR, device binding, and Dynamic Key v2.

Device identification

{
  "device": {
    "id": "installation-uuid",
    "platform": "ios" | "android"
  }
}

Typical flow

1. v2 handshake when the app opens (or when refreshing the token).
2. Login via encrypted /users/login on the allowlist.
3. QR: GET /qr/get/reverse/:BFP to link the device.
4. Include the device header on legacy routes that require it.

Suggested libraries

• iOS: CryptoKit (P-256), Security framework.
• Android: KeyPairGenerator EC + Cipher AES-GCM.

Offline / reconnection

If expiresAt has expired, repeat the handshake before any encrypted request. Do not cache encrypted responses without validating integrity (GCM auth tag).

Backend Guide

Server-to-server integration and external SDK for partners.

External client (SDK)

{
  "client": {
    "type": "external",
    "clientId": "partner-acme-corp"
  },
  "device": {
    "id": "server-instance-id",
    "platform": "server"
  }
}

Allowlist and restrictions

external clients only access explicitly enabled routes. Any other route returns DYNAMIC_KEY_V2_ROUTE_NOT_ALLOWED.

Downstream microservices

The gateway decrypts, validates the allowlist, and forwards to internal services (Auth, QR, etc.). Microservices do not implement Dynamic Key — they receive normal HTTP requests from the gateway.

Required configuration

• JWT_SECRET from Store Keys (/getKeys).
• Service URL variables (AUTH_SERVICES_URL, etc.).
• Logs with safeErrorLog — do not expose secrets.

QA Guide

Practical layer to validate that OpenAPI contracts work at runtime. Full reference in qa/.

What to test on /api/info/v2

What to test on /api/request/v2

Release checklist

• ☐ Spec published and versioned in contracts/
• ☐ Smoke test per category (Auth, QR, Companies, Catalogs)
• ☐ Negative cases: nonce, token, route, session
• ☐ Sanitized examples (no real passwords)
• ☐ Portal points to the correct environment

Reference files

• qa/dynamic-key-v2.md — handshake and proxy
• qa/sdk-web-v2.md — Web SDK integration
• qa/critical-routes.md — P0/P1 routes
• qa/error-cases.md — error catalog

DOCS / CONTRACTS / QA Architecture

How the three Nimbus documentation layers relate.

CONTRACTS — OpenAPI Specs

YAML files that define the real technical contract. Swagger reads them to render endpoints, schemas, and examples.

contracts/
├── api-gateway-v2.yaml      ← microservice-apigateway-v2
├── key-management-v2.yaml   ← microservice-key-management-v2
└── upcoming/                ← future service specs

sdk/nimbus-sdk-web-v2        ← @nimbus/sdk-web (client library)

DOCS — Developer Portal

This centralized portal. API spec selector, environment selector, Swagger UI, guides, and Dynamic Key v2 documentation — decoupled from application runtimes.

docs-api-dev.nimbus-id.com   → development
docs-api-stg.nimbus-id.com   → staging
docs-api.nimbus-id.com       → production

QA — QA Reference

Practical guides: critical routes, headers, positive/negative cases, checklists.

Linked from specs via x-qa-ref.

DevSecOps pipeline (target)

Summary

• DOCS = where you view it
• CONTRACTS = what defines the API
• QA = how you test it