Wallet signing and key API migration

Wallet key actions require the signed-in account owner’s merchant JWT and an interactive window at https://sign.inzipay.com . Payment integration API keys (sk_live_ / sk_test_) cannot open these sessions. There is no unattended server-to-server replacement for obtaining a vendor token, creating a passkey or exporting a wallet key.

Retired endpoints

The following authenticated POST routes now return 410 SIGN_WINDOW_REQUIRED. Their response includes this guide’s URL in error.details.migrationUrl. They do not issue a token or record a passkey, attempt, wallet, rekey or export.

Old route under `/api/v1/wallets`	Replacement
`/embedded/token`	Select a wallet action below; Sign obtains its own task-bound access. No generic token replacement.
`/embedded/encryption-session`	Sign handles the key ceremony; never request an encryption session from the integration.
`/embedded/attempt`	Open `wallet_create` or `wallet_import`.
`/embedded/passkeys`	Open `wallet_create`, `wallet_import` or `passkey_reissue`; Sign registers its credential.
`/embedded`	Open `wallet_create` or `wallet_import`; Sign proves ownership before a wallet is recorded.
`/embedded/:id/rekey/release` and `/complete`	Open `passkey_reissue` with the existing wallet’s `address` and `namespace`.
`/embedded/:id/exported`	Open `wallet_export` for a `walletId`, or `wallet_backup`; do not report export completion yourself.

Read GET /api/v1/wallets/embedded to obtain recorded wallet IDs and addresses. Its available, signMediator and signWindowConfigured fields describe account access and deployment readiness; a missing field or failed read does not enable a direct-key fallback. Read, rename, removal-report and forget-wallet routes remain separate operations.

Open a session

Send this JSON to POST /api/v1/signing-sessions, authenticated with the owner’s merchant JWT. This example opens EVM wallet creation; it does not change payment routing automatically.


{
  "kind": "wallet_create",
  "namespace": "eip155",
  "routeIfFree": false
}

The response’s data contains signingSessionId, signerUrl, mode: "window" and expiresAt. It does not contain a key, PRF result or vendor token. A disabled signer/account returns an error; show it instead of falling back to old routes.

Accept only the exact https://sign.inzipay.com origin, /w path, no query or user information, and a fragment equal to the returned session ID.
Show an Open inzi sign button. Open the returned URL from that button’s click so the browser can allow the popup. Report a blocked popup and let the person retry. Do not embed Sign in an iframe or send the merchant JWT to it.
The person reviews and completes the action inside Sign. Only Sign calls /sign/v1/*; integrations must not claim the session or obtain key material.
Poll GET /api/v1/signing-sessions/outcome with the same merchant JWT and Signing-Session: <the returned signingSessionId>. Treat window messages only as a prompt to read that subject-bound server outcome. Never trust a client-supplied success flag.

A reload, expired session or already claimed session requires a newly opened session. A signed outcome means the session’s required proof was accepted; it does not prove that a financial transaction completed. Follow the operation’s status and original transaction identity; an unknown result is not permission to send again.

Other key actions

Session kind	Additional fields
`wallet_import`	`namespace: "eip155"`; enter the key only in Sign. Solana import is unavailable; use `wallet_create` with `namespace: "solana"` instead.
`wallet_export`	A recorded `walletId`.
`wallet_backup`	Optional `walletId`; omit it for the account’s wallet backup.
`passkey_reissue`	Recorded `address` and `namespace`; derived Tron uses its underlying EVM wallet.
`wallet_repair`	A recorded EVM `walletId`, for explicit backup repair.

New wallet passkeys belong to sign.inzipay.com. Existing passkeys under the cabinet’s RP ID retain a residual isolation risk until reissued through Sign; reissue preserves the wallet address. Historical custodial alpha is excluded by Tim’s decision in INZI-596 .

Existing devices when the vault origin changes

Sign’s key runtime is separate from the dashboard. The vault cutover moves its vendor frame to vault.inzipay.com; the dashboard cannot embed that frame directly. Moving that frame to a new origin does not move its old browser storage. Each device therefore restores its local share once using the existing wallet passkey. The recorded wallet address stays the same; do not create another wallet or choose Repair from backup just because the runtime origin changed.

After the vault release, use this flow to check the existing wallet without sending funds:

Open Wallets, find the existing wallet and compare its address with your recorded address. Choose Check it signs here, then Open inzi sign.
In the top-level sign.inzipay.com window, check the wallet address, network and text under Verify your inzi wallet. This is an ownership message: No money moves. Confirm with your passkey in that window.
Wait for the dashboard to report that this device signed and the server accepted it. A window message or closed popup alone is not acceptance. Confirm that the recorded address is unchanged.

An unavailable passkey or failed recovery is an error to resolve on the owner’s device. It does not justify a new wallet, altered payment routing, key repair or a repeated transfer. Existing passkeys still tied to the cabinet’s RP ID need the separate Move passkey action through Sign to complete that isolation boundary; restoring the device share does not change the passkey’s RP ID.