Backend API¶
This page documents the partner-facing API surface. Examples use sandbox placeholder hosts and credentials.
| Environment | Base URL |
|---|---|
| Test | https://ptest.yanez.ai |
| Production | https://yid.yanez.ai |
Validate a Record¶
POST /api/partners/records/validate
Confirms whether a Yanez identity record exists and, optionally, that a public key is bound to it. This is the only registry endpoint — there is no separate registration step. Yanez manages the yid-key binding; partners use this endpoint to verify it.
Run this after verifying the user's callback signature, before persisting the binding. Returns booleans, not the record.
This endpoint requires signed partner request authentication.
Request¶
{
"yid": "796aaf67d496447fa4059dcea80b03aa",
"public_key": "0x3b6a0f..."
}
| Field | Required | Notes |
|---|---|---|
yid |
yes | Opaque 32-char hex record ID, case-insensitive. Validate only that it is 32 hex characters — do not assert UUID structure. |
public_key |
no | The user's public key for this yid. Raw hex, 0x prefix optional, case-insensitive. Ed25519 = 64 hex chars; BLS12-381 G1 = 96 hex chars. Omit to check yid only. |
Unknown fields are rejected with 422.
Response — 200 OK¶
{
"yid_valid": true,
"public_key_valid": true
}
The pair is confirmed only when both are true.
yid exists |
public_key sent |
Key bound | yid_valid |
public_key_valid |
|---|---|---|---|---|
| yes | no | — | true |
null |
| no | no | — | false |
null |
| yes | yes | yes | true |
true |
| yes | yes | no | true |
false |
| no | yes | — | false |
false |
An unknown yid returns 200 with yid_valid: false — not a 404. Branch
on the booleans, not the HTTP status. The endpoint only tells you whether the
key you supplied is bound — it never enumerates the keys on a record. A yid
may carry several keys; this endpoint only tests membership. Duplicate
detection happens at enrollment.
Errors¶
| Status | When |
|---|---|
400 |
yid not 32 hex chars; public_key non-hex or outside 32–256 bytes. |
401 |
Signature or auth failed — generic, never says which check failed. |
422 |
Missing yid, unknown field, or invalid JSON body. |
429 |
More than 60 requests per 60 seconds per IP. Enforced before auth, so it can precede a 401. Body: {"detail":"Too many requests"}. |
Python Example¶
import base64, hashlib, json, secrets
from datetime import datetime, timezone
from typing import Optional
import requests
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
BASE_URL = "https://ptest.yanez.ai"
PARTNER_ID = "ptr_..."
KEY_ID = "key-1"
PRIVATE_KEY = "..." # 32-byte Ed25519 private key as hex
def b64url(raw: bytes) -> str:
return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
def validate_pair(yid: str, public_key: Optional[str] = None) -> dict:
path = "/api/partners/records/validate"
payload = {"yid": yid}
if public_key is not None:
payload["public_key"] = public_key
body = json.dumps(payload).encode()
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
nonce = secrets.token_urlsafe(18)
body_hash = b64url(hashlib.sha256(body).digest())
canonical = "\n".join([
"YANEZ-SIG-V1", "POST", path, PARTNER_ID, KEY_ID, "EdDSA",
timestamp, nonce, body_hash,
]).encode()
sig = b64url(Ed25519PrivateKey.from_private_bytes(bytes.fromhex(PRIVATE_KEY)).sign(canonical))
headers = {
"Content-Type": "application/json",
"X-Yanez-Partner-Id": PARTNER_ID,
"X-Yanez-Key-Id": KEY_ID,
"X-Yanez-Signature-Alg": "EdDSA",
"X-Yanez-Timestamp": timestamp,
"X-Yanez-Nonce": nonce,
"X-Yanez-Content-SHA256": body_hash,
"X-Yanez-Signature": sig,
}
resp = requests.post(BASE_URL + path, data=body, headers=headers, timeout=10)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
result = validate_pair(yid="<yid>", public_key="0x<hex>")
confirmed = result["yid_valid"] and result["public_key_valid"]
print("Confirmed" if confirmed else f"Rejected: {result}")
Send a Signing Request by Push¶
POST /api/partners/signing-requests
Sends a signing request to the user's phone as a push notification, so the user
doesn't have to scan a QR code. You send the same signed link you would show as
a QR code, plus the user's yid. Yanez stores the link for five minutes and
notifies every phone registered for that yid. The first phone to open the
notification gets the request; another phone that opens it sees an expired
message. After that, the flow is the same as a scanned QR code, and the result
arrives at your callback.
This endpoint requires signed partner request authentication.
The authenticated partner must be the partner whose app_id is in the link.
Request¶
{
"payload": "https://yid.yanez.ai/open?message=...&callback=...&method=post&request_id=...&event=transaction.signed&description=...&terms=...&app_id=ptr_...&kid=key-1&app_sig=...",
"yid": "796aaf67d496447fa4059dcea80b03aa"
}
| Field | Required | Notes |
|---|---|---|
payload |
yes | The complete signed link, up to 4,096 characters. See Deep-Link Signing. |
yid |
yes | The user's 32-character hex yid. |
Response — 201 Created¶
{
"request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"expires_at": "2026-10-06T18:05:00Z"
}
201 means Yanez stored the request. It doesn't mean a phone received the
notification. If the user never responds, the request expires at expires_at.
Errors¶
| Status | When |
|---|---|
400 |
The link's terms is invalid. detail names the problem, for example terms.title must be a non-blank string. Also returned for terms requires method=post and terms must appear at most once. |
400 |
The link is malformed or has no valid request_id. |
401 |
Request authentication or the link's app_sig failed. |
403 |
The link was signed by a different partner than the one calling. |
404 |
Unknown yid. |
409 |
This request_id was already used. |