Skip to content

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.