Authentication

HeritagePay uses separate authentication models for end users and institution operators.

Plane A: mobile end users

Plane A is driven by phone number, OTP, and PIN:

1. POST /auth/otp/issue
2. POST /auth/otp/verify
3. POST /auth/register or POST /auth/login
4. Use Authorization: Bearer <accessToken>
5. Rotate with POST /auth/refresh
6. Revoke with POST /auth/logout

Mobile requests also send:

Code
X-Deployment-Scope: end-user

Plane B: operators and integrations

Plane B uses institution API keys:

Code
X-Plug-Wallet-Api-Key: <api-key>

Routes that mutate sensitive operator state may also require HMAC signing. Keep that signing code server-side; do not place Plane B keys inside mobile apps.

Developer portal login

This Zudoku portal supports Clerk, Auth0, OpenID Connect, or Supabase. Configure one provider in .env:

Code
ZUDOKU_PUBLIC_AUTH_PROVIDER=openid
ZUDOKU_PUBLIC_OPENID_ISSUER=https://identity.example.com/realms/heritagepay
ZUDOKU_PUBLIC_OPENID_CLIENT_ID=heritagepay-dev-portal

When a provider is configured, API reference and operational pages are protected and the API playground can sign requests using the developer's session.