Attestations

An attestation is a compact, Ed25519-signed token (JWT-shaped: base64url(header).base64url(payload).base64url(signature), alg: EdDSA) asserting selected claims about an approved verification. It is the mechanism that lets the rest of your products — or a partner — trust a verification without ever receiving identity data.

Requesting

POST /v1/attestations/{verification_id}
Authorization: Bearer <API_KEY>

{ "claims": ["verified", "over_18"] }

Selective disclosure is the point: ask only for what the consuming system needs. An age-gated product needs over_18 — not the name. Every issuance (and its claim list) is audit-logged.

Claim	Type	Notes
verified	boolean	The core assertion
over_18	boolean | null	Computed from DOB at issuance time
name	string	Given names + family name as extracted
date_of_birth	string	ISO date — request only if you truly need it
document_country	string	ISO 3166-1 alpha-3 issuing country

Standard fields: iss (baqshi-kyc), sub (the verification ID), iat, exp (default 365 days).

Verifying (any consumer, offline)

Fetch the public key once from GET /v1/attestations/public-key (PEM, Ed25519) and pin it in the consuming service:

import base64, json
from cryptography.hazmat.primitives.serialization import load_pem_public_key

def verify_attestation(token: str, public_key_pem: str) -> dict:
    header_b64, payload_b64, sig_b64 = token.split(".")
    unb64 = lambda s: base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
    load_pem_public_key(public_key_pem.encode()).verify(
        unb64(sig_b64), f"{header_b64}.{payload_b64}".encode()
    )  # raises InvalidSignature on tamper
    payload = json.loads(unb64(payload_b64))
    assert payload["exp"] > time.time(), "attestation expired"
    return payload

Any JOSE library that supports EdDSA works too. Because verification is offline, consumers don’t need network access to (or an account with) BAQSHI-KYC.

Lifecycle notes

• Attestations are point-in-time statements. If you later erase a user’s data, the already-issued attestation remains mathematically valid — build consuming systems to honour exp, and keep TTLs as short as your use case allows.
• Key rotation: publish the new public key alongside the old at the consumer level during a transition window, then retire the old.