OpenWave Identity Registry

One username across every participating bank.

OpenWave Identity is the routing authority for NPT handles. Customers own the global username, banks vouch for accounts they hold, and gateways resolve aliases without exposing account data to merchants.

Read NPT model Download OpenAPI

Resolution example Public API

Customer handle tellesy

tellesy@andalusAndalus account

tellesy@nubNUB account

GET /v1/identity/resolve?alias=tellesy

Ownership model

The registry separates username ownership from bank account authority.

The customer owns the global handle. Each bank can attach only accounts it has vouched for. Gateways resolve routing data, but private bank data remains behind the bank boundary.

Handle lifecycle

Claim, link, choose default, resolve.

1Customer claims `tellesy` through a bank 2Bank links a vouched account 3Customer chooses default route 4Gateways resolve without seeing secrets

Registry data flow

Gateways get routing answers, not private banking data.

The registry returns the bank handle, account route metadata, and ownership status needed to continue the OpenWave flow. Authentication, balances, account numbers, and CBS actions stay with the bank.

Boundaries

Identity only. Not a wallet, not a gateway.

Customer ownership

The customer owns the global username and chooses which linked account is default for unqualified payments.

Bank-scoped authority

A bank can claim or update only the accounts it has KYC-vouched for. It cannot rename the global handle.

Gateway resolution

Gateways resolve handles before routing payments or Open Banking handoffs through OpenWave-compatible rails.

Who can do what

The registry protects customer ownership while giving banks the tools they need.

Actor	Allowed	Not allowed
Customer	Own the global username, choose default account, revoke visibility where policy permits, recover access through governed flows.	Bypass bank KYC to link accounts the bank has not vouched for.
Bank	Claim or link accounts it owns, update account status, resend credentials for its customer channels, suspend bank-scoped links for risk.	Rename the customer's global username or modify accounts belonging to another bank.
Gateway	Resolve aliases for payment routing, cache short-lived route metadata, and continue OpenWave checkout or consent.	Treat cached aliases as ownership truth when the registry is unavailable.
Registry admin	Govern bank onboarding, namespace disputes, fraud holds, recovery policy, and audit access.	Expose private account data to merchants or gateways outside explicit routing needs.

Endpoint map

Small surface, strict responsibility.

GET/v1/identity/resolve

Public alias resolution for gateways and apps.

POST/v1/identity/claim

Bank-vouched handle claim using an OpenWave bank key.

POST/v1/identity/{handle}/accounts

Link a bank-owned account to an existing handle.

PATCH/v1/identity/{handle}/default

Set the customer default receiving account.

GET/v1/banks

Public participating bank directory and routing phonebook.

GET/v1/registry/info

Registry operator, governance, and source metadata.

OpenAPI and client tooling

Use the same machine-readable contract everywhere.

Download and inspect

The Identity Registry contract is published in the OpenWave spec repository as OpenAPI 3.0 YAML.

Download YAML Open in Swagger

Postman import

In Postman, choose Import, then Link, and paste the raw YAML URL below.

https://raw.githubusercontent.com/neptune-ly/openwave-spec/main/openwave-identity-v1.0.yaml

Environment variables

IDENTITY_URL for the registry base URL.
BANK_KEY for `X-OpenWave-Bank-Key: owbk_...`.
CORRELATION_ID for tracing test calls.

Generated clients

npx @openapitools/openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/neptune-ly/openwave-spec/main/openwave-identity-v1.0.yaml \
  -g typescript-fetch \
  -o ./openwave-identity-client

Standard error shape

Errors are explicit, traceable, and safe to show where appropriate.

Alias not found

{
  "error": {
    "code": "ALIAS_NOT_FOUND",
    "message": "Alias was not found in the identity registry.",
    "retryable": false,
    "correlation_id": "corr_01HX7V7XT5Y7C7G5WM3H8S5W5P"
  }
}

Bank link forbidden

{
  "error": {
    "code": "BANK_ACCOUNT_SCOPE_FORBIDDEN",
    "message": "This bank cannot modify an account owned by another bank.",
    "retryable": false,
    "correlation_id": "corr_01HX7Z4T2V1M7J6HEAWMF6Q9E3"
  }
}