Copy page

Start here

Authentication and authority

PayPM separates end-user credentials, institution operator credentials, and platform OIDC subjects. Do not mix these planes in a single client.

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

OTP issue, OTP verify, register, and login are tenant-scoped. Live sandbox requires businessEntityId on those bodies. OTP issue also requires channel: "sms" (a {phone, purpose} body returns 400). OTP verify uses otpChallengeId + code, not phone+code alone. See Quickstart.

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.

ZITADEL: platform authentication authority

Platform interactive clients (developer portal, Marketplace SPA, and other OIDC apps) authenticate against the shared ZITADEL issuer:

Surface	Value
Issuer	https://auth.paypm.net
Discovery	https://auth.paypm.net/.well-known/openid-configuration
Console	https://auth.paypm.net/ui/console

ZITADEL authenticates subjects only. It does not own product tenants, Marketplace roles, KYC/KYB state, or wallet links. Create a dedicated ZITADEL application per client (mobile, portal, backoffice, developer portal, Marketplace SPA). Never reuse one client across product surfaces.

Identity ownership

After ZITADEL authenticates a subject, PayPM Identity resolves that subject into canonical person, business, and membership facts:

Code
{
  "personId": "uuid",
  "status": "active",
  "business": {
    "businessId": "uuid",
    "publicReference": "tenant-or-business-ref",
    "membershipStatus": "active"
  },
  "externalReferences": {
    "walletEndUserId": "optional-uuid"
  }
}

Standalone Marketplace calls the private Identity API at:

Code
POST {IDENTITY_SERVICE_URL}/internal/v1/authentication-subjects/resolve

with a ZITADEL service JWT. Identity does not return product roles. Marketplace participant roles such as supplier and operator remain in the Marketplace database.

See PayPM Identity for bind, person/business reads, updates, and membership listing.

Marketplace and other product APIs must refuse actors that lack an active Identity context or the required product participant role. Authentication claims never become tenant or role authority.

Compatibility mode (IDENTITY_DIRECTORY_MODE=compatibility with IDENTITY_COMPATIBILITY_CONTEXTS_JSON) is a time-boxed adapter only. Sandbox Marketplace now uses http mode against the private Identity API.

Developer documentation boundary

developer.paypm.net is public, read-only documentation. It has no login and does not sign API requests with a browser session. A ZITADEL token is not a Plane B institution credential and must never be presented as one.

Partner API keys, webhook controls, environment settings, and other mutations remain in governed product surfaces. A future authenticated developer workspace requires a dedicated ZITADEL client plus a server-side PayPM Platform developer membership check. It cannot inherit Partner Console administrator authority.