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

```text
X-Deployment-Scope: end-user
```

## Plane B: operators and integrations

Plane B uses institution API keys:

```text
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`:

```text
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.