The Mask.ID Attestation API

Let your users prove they are established, reputation-backed people — no email, no phone number, no bots. Your site receives the member’s Trust Index and, with their permission, the reputation evidence behind it. You never learn who they are on Mask.ID.

Quick start: download the single-file example relying party — maskid-example-rp.js (Node 18+, zero dependencies). Run node maskid-example-rp.js, open localhost:8080, and receive your first verified attestation in redirect mode with nothing publicly hosted. It implements the entire verify procedure documented below.

Scope packs

Your request's scopes list names the packs below by id; the member approves or unchecks each one at verification time. The Trust Index itself rides every grant — no scope needed.

Data points

Each row names the scope that carries it. Live ships today. Live · Opt-in is never pre-checked — the member must deliberately turn it on. Never available is a design guarantee, not a default: those rows can’t be requested, bought, or opted into.

The full picture — every live field at once

A response with every pack and opt-in granted (generated from the same catalog the server builds payloads from; multi-value rows show a representative key). Real responses carry only the granted, statable fields.

{
  "v": 1,
  "type": "maskid.attestation",
  "key_id": "…", "subject_id": "msub_…",
  "rp_host": "your-site.example", "rp_user_id": "u_8347", "nonce": "…",
  "scopes": ["trust_index", "profile", "referrals", "reputation",
             "presence", "commitment", "mno", "location", "platforms"],
  "trust_index": 87,
  "profile_type": "individual",
  "earned_username": true,
  "account_age": "1–2 years",
  "active_within": "30 days",
  "founding_member": true,
  "invited": true,
  "mno_verified": true,
  "region": "North America",
  "referrals_score": 72,
  "referrals_received": "25+",
  "referrals_given": "10+",
  "referrer_avg_ti": 64,
  "referrers_verified_pct": 80,
  "referral_recent": true,
  "trust_score": 78, "trust_tier": "Established",
  "identity_score": 84,
  "real_person": 92,
  "avg_years_known": "4 years",
  "met_in_person_pct": 40,
  "recommend_pct": 95,
  "professional_rep": 88,
  "presence_score": 75,
  "verified_platforms": 3,
  "crypto_linkage": true,
  "platforms": ["github", "x"],
  "oldest_identity": "5+ years",
  "capital_score": 61,
  "commitment": "1k–10k PIV",
  "coin_age_all": "10k–100k PIV-days",
  "coin_age_6mo": "1k–10k PIV-days",
  "coin_age_3mo": "1k–10k PIV-days",
  "coin_age_30d": "100–1k PIV-days",
  "backed": true,
  "tipped_by": "5+ members",
  "tipped": "10+ members",
  "parked_held": "3+",
  "names_bought": "1+",
  "names_sold": "1+",
  "attested_sites": "3+",
  "issued_at": "2026-08-14T15:02:09Z",
  "api": "…/api/attest/v1/subject/msub_…"
}

Edge cases your integration must expect

• Absent fields are normal, not errors. A field is omitted when the member declined its scope, the value is unset, or a privacy floor withholds it. Code for presence, never for position or completeness.
• "trust_scores": "gated" replaces the whole reputation pack while the member has fewer than ten referrers — informative in itself.
• The subject read answers 404 identically for unknown, revoked, and malformed subjects — treat any 404 as “no longer verified,” and expect it the moment a member revokes.
• Bucket values are display text ("1k–10k PIV", "25+") subject to refinement — compare for presence or equality, never parse them.
• Webhook delivery retries a few times; any 2xx from you stops it. Verify-then-store must be idempotent per nonce.

How verification works

1. Your site shows a verification request (QR + copyable string) to a user who clicked “Verify with Mask.ID”:

   {
     "v": 1,
     "rp_user_id": "u_8347",
     "nonce": "d41d8cd98f00b204e9800998",
     "webhook": "https://your-site.example/maskid/callback",
     "redirect": "https://your-site.example/settings/verified",
     "scopes": ["trust_index", "reputation", "commitment"]
   }

2. The user reviews exactly what you’ll receive and approves it with a wallet signature on their Mask.ID.
3. Mask.ID POSTs a signed response to your webhook (and/or returns the user to your redirect URL carrying the same response):

   {
     "v": 1,
     "type": "maskid.attestation",
     "subject_id": "msub_k5r2…",
     "rp_user_id": "u_8347",
     "nonce": "d41d8cd98f00b204e9800998",
     "scopes": ["trust_index", "reputation", "commitment"],
     "trust_index": 87,
     "trust_score": 78, "real_person": 92, "recommend_pct": 95,
     "commitment": "1k–10k PIV", "coin_age_all": "10k–100k PIV-days",
     "issued_at": "2026-08-13T14:02:09Z"
   }

4. You verify one Ed25519 signature against the published platform key, store the subject_id, and may re-read the granted data while the member’s permission stands.

Endpoints

API keys & pricing

During the pilot, verification and the subject read are free and keyless. API keys, volume tiers, and self-serve signup will land on this page. Building something against this? We’d like to hear from you — use the Contact form in the footer.

Are you a Mask.ID member? The other half of this flow is yours: Verify Trust Index.