Callback Verification¶
After the user completes a Yanez flow, YanezYID POSTs the signed result directly to the partner backend's callback URL — not through the client. The callback may arrive from a different device (cross-device QR scan).
The callback endpoint is not authenticated by the user's session. Its trust
comes entirely from the single-use challenge: the request_id must map to a
pending, unexpired challenge that the backend issued, and the signed bytes must
equal that challenge exactly.
Callback Payload¶
This section and Verification Steps describe links
without terms. For a link with terms, see Signed Decisions.
YanezYID POSTs application/json:
{
"request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"yid": "<stable unique yid>",
"message": "<the exact base64url message from the deep link>",
"keys": [
{ "threshold_tier": "low", "group_public_key": "0x<48-byte G1 hex>", "eth_address": "0x<EIP-55>" },
{ "threshold_tier": "medium", "group_public_key": "0x<48-byte G1 hex>", "eth_address": "0x<EIP-55>" },
{ "threshold_tier": "high", "group_public_key": "0x<48-byte G1 hex>", "eth_address": "0x<EIP-55>" }
],
"matched_tier": "high",
"signature": "0x<96-byte G2 hex>"
}
| Field | Notes |
|---|---|
request_id |
Correlates the callback to the challenge the backend issued. |
yid |
Stable unique Yanez ID for the user. |
message |
The exact message value from the deep link, base64url-encoded. |
keys |
One entry per threshold tier. The app always sends all registered tiers (enrollment and step-up alike); for step-up only the matched_tier entry is strictly required to verify. |
matched_tier |
The tier whose key produced signature. |
signature |
A single BLS12-381 G2 signature (96 bytes), produced by the matched tier's key. |
Successful callbacks include both matched_tier and signature. In redirect
mode, parse them as optional query parameters: if either is absent, the callback
cannot pass Verification Steps 3–4.
The callback carries no verification-status flag. The backend MUST independently verify the BLS signature (see Verification Steps) and never trust any client-asserted "verified" state.
Delivery Modes¶
The deep link's method parameter selects how YanezYID returns the result:
method |
Delivery |
|---|---|
post |
The payload above is sent as an application/json POST body to the callback URL. |
redirect |
The same fields are returned as query parameters appended to the callback URL (keys is serialized as a JSON string parameter). |
There is no callback-domain allowlist on either platform: post delivers to
whatever URL the signed link carries. Use an HTTPS endpoint on your own backend
that is reachable from the public internet — the request comes from the user's
phone, not from Yanez servers.
Respond to a post callback with 2xx. YanezYID treats any 2xx as
delivered. Any other status is shown to the user as a failed signing — a
STATUS · TITLE header over the message — and is never retried, so the user
must start a new signing. The app maps statuses to messages as follows; return
the specific ones deliberately or not at all:
| Your response | Return it when | What the user sees |
|---|---|---|
2xx |
Every verification step passes. | Success — the app dismisses silently. |
400 |
The payload can't be parsed: missing fields, bad encoding, or an invalid matched_tier (step 3). |
400 · BAD REQUEST — "Partner rejected the request." |
401 |
The signature, keys, or message fail verification (steps 2, 4–7, or 9). | 401 · SIGNATURE REJECTED — "Partner rejected the signature." |
403 |
Step-up: matched_tier is below required_tier (step 8), or your policy denies the action. |
403 · STEP-UP REQUIRED — "Additional verification required or denied." |
404 |
request_id is unknown (step 1). |
404 · CHALLENGE NOT FOUND — "Unknown or expired signing request." |
409 |
request_id was already consumed — a duplicate or replayed delivery (step 1). |
409 · ALREADY USED — "This request was already signed or is a duplicate." |
410 |
request_id has expired (step 1). |
410 · CHALLENGE EXPIRED — "This signing request has expired." |
5xx |
Your backend failed before it could verify. | 5xx · PARTNER ERROR — "The partner service had an error." |
other 4xx |
Anything else. | 4xx · REJECTED — "Partner rejected the delivery." |
If the phone gets no HTTP response at all, the user sees CONNECTION FAILED —
"Couldn't reach the partner. Please try again." — which also isn't retried.
The verification steps below are identical for both modes — always verify the
signature over the decoded message bytes regardless of how the result arrived.
Verification Steps¶
These steps apply to links without terms. For a link with terms, follow
Verifying a Signed Decision instead: the
callback carries a signed envelope rather than your message, and you mark the
request used only after a callback passes.
All of the following must hold before the callback is accepted. Mark the challenge consumed on first receipt, regardless of outcome — challenges are single-use even if verification fails.
request_idmaps to a stored challenge that is not expired and not consumed. Mark it consumed immediately.- Decoded
messagebytes are byte-for-byte equal to the canonical challenge the backend issued for thisrequest_id. matched_tieris a valid tier and is present inkeys.- The matched key's
group_public_keyis 48 bytes;signatureis 96 bytes. - BLS verifies
signatureagainst the matchedgroup_public_keyover the decodedmessagebytes. - For each entry in
keys,eth_addressequalsderive_address(group_public_key). Store the server-derived address — do not trust the client-supplied value. - Enrollment only: all tiers in
keyspass step 6; store the full key set with deduplication. - Step-up only:
matched_tier ≥ required_tier, and the matchedgroup_public_keyequals the key stored for this user and tier at enrollment. - (Recommended) Call
POST /api/partners/records/validateto confirm the(yid, group_public_key)pair against the Yanez registry.
BLS Verification¶
The signature scheme is BLS12-381 G2Basic with DST
BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_.
from py_ecc.bls import G2Basic
PUBKEY_LEN, SIG_LEN = 48, 96
def verify_bls(pubkey_g1: bytes, message: bytes, signature_g2: bytes) -> bool:
if len(pubkey_g1) != PUBKEY_LEN or len(signature_g2) != SIG_LEN:
return False
try:
return bool(G2Basic.Verify(pubkey_g1, message, signature_g2))
except Exception:
return False
message is the decoded (raw bytes) value of the message field — the same
bytes YanezYID signed verbatim.
Signed Decisions¶
When your link includes terms,
YanezYID sends a signed decision instead of signing your message directly.
The user approves or declines with a face scan, and either way you receive a
callback.
Decision Callback Payload¶
The callback has the usual fields plus two more:
| Field | Contents |
|---|---|
message |
Base64url of the exact signed envelope bytes (see below). |
signature |
BLS signature over those bytes, made with the decision domain tag. |
keys, matched_tier, request_id, yid |
Same as in Callback Payload. |
decision |
approve or reject, copied from the envelope. |
terms |
Your terms, copied from the envelope. |
Act only on values inside the verified envelope. decision and terms are
copies for convenience.
The Envelope¶
The decoded message is a JSON object:
{
"action": "partner_signing.decision",
"app_id": "ptr_416582cd9ea9bb6c3750de1c",
"assurance_tier": "high",
"decision": "approve",
"message": "<your message value, unchanged>",
"request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"signed_at": 1791234567,
"terms": { "title": "…", "summary": "…", "details": [] },
"version": 1,
"yid": "<stable unique yid>"
}
Parse the bytes you received. Don't re-encode the JSON before verifying.
Domain Tag¶
A domain tag is a fixed label mixed into a BLS signature, so a signature made under one tag never verifies under another. Signed decisions use:
YANEZ_PARTNER_DECISION_V1_BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_
Links without terms keep the tag in BLS Verification.
The separate tag means a signature from an ordinary link can never pass as a
signed decision.
from py_ecc.bls import G2Basic
class DecisionBLS(G2Basic):
DST = b"YANEZ_PARTNER_DECISION_V1_BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_"
def verify_decision_signature(pubkey_g1: bytes, envelope: bytes, signature_g2: bytes) -> bool:
if len(pubkey_g1) != 48 or len(signature_g2) != 96:
return False
try:
return bool(DecisionBLS.Verify(pubkey_g1, envelope, signature_g2))
except Exception:
return False
Verifying a Signed Decision¶
The callback isn't authenticated, so anyone who learns a request_id can send
one. Ignore any callback that fails these checks, and mark the request used
only after one passes. A failed callback must leave the request open, so the
user's real callback still gets through.
request_idmaps to a request you issued that isn't expired or already decided. Don't mark it used yet.- Check that
matched_tierislow,medium, orhigh. Then decodemessageand verifysignatureover those exact bytes with thekeysentry whosethreshold_tierequalsmatched_tier, using the decision domain tag. - Parse the envelope and check that:
versionis1andactionispartner_signing.decision.decisionisapproveorreject.app_idis yourpartner_id.request_idequals the callback'srequest_id.yidis the user you sent the request to.assurance_tierequalsmatched_tier.messageequals themessageyou put in the link.termshas the same keys and values as thetermsyou sent.signed_atfalls within the request's lifetime.
- Required: call
POST /api/partners/records/validatewith theyidand the matchedgroup_public_key, and require both results to betrue. The callback reports its own keys, so without this check a forged callback could carry someone else's key. - If you require a minimum tier, compare the matched key with the per-tier
keys you stored at enrollment, as in step 8 of
Verification Steps.
records/validateconfirms the key belongs to theyid, not which tier it is. - In one atomic step, mark the request decided and record
decision. If a valid callback already decided it, ignore this one. - Act on the recorded
decision. Perform the requested action only forapprove; treatrejectas the user declining.
Respond 2xx to every callback that passes these checks, including a valid
decline. YanezYID shows any other status to the user as a failed delivery.
A callback whose message isn't an envelope, after you sent terms, came
from an older YanezYID. Ignore it; if the request expires without a valid
callback, treat it as not approved.
Address Derivation¶
from eth_utils import keccak, to_checksum_address
def derive_address(pubkey_g1: bytes) -> str:
# EIP-55 checksum address derived from the BLS G1 public key.
# This is a stable identifier — it is NOT a usable Ethereum address.
return to_checksum_address(keccak(pubkey_g1)[-20:])
Client Result Delivery¶
The client learns the outcome by polling a status endpoint or via push (SSE) —
never as a direct reply to the signing hop. Correlate by request_id.