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 starts unchecked — the member must deliberately turn it on (the payment link is the one exception: it starts on, and the member may turn it off). 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", "humanity", "mno", "location",
             "platforms", "pay_link"],
  "trust_index": 87, "trust_index_tier": "trusted",
  "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,
  "identity_consistent": 90,
  "owns_user_id": 85,
  "familiarity": 80,
  "capacity_mix": {"colleague": 40, "client": 60, "community": 30},
  "active_relationship_pct": 80,
  "long_standing_current_pct": 30,
  "trust_money_pct": 80,
  "trust_property_pct": 70,
  "trust_care_pct": 60,
  "trust_advice_pct": 90,
  "trust_meet_pct": 90,
  "frequent_contact_pct": 50,
  "transacted_pct": 60,
  "settled_as_agreed_pct": 90,
  "sole_operator": 90,
  "conduct": 95,
  "responsiveness": 85,
  "avg_years_known": "4 years",
  "met_in_person_pct": 40,
  "video_calls_pct": 60,
  "audio_calls_pct": 40,
  "project_together_pct": 50,
  "recommend_pct": 95,
  "professional_rep": 88,
  "personal_reliability": 85,
  "commitment_reliability": 85,
  "presence_score": 75,
  "verified_platforms": 3,
  "crypto_linkage": true,
  "platforms": ["github", "x"],
  "oldest_identity": "5+ years",
  "capital_score": 61,
  "capital": {
    "pivx": {"unit": "PIV", "commitment": "1k–10k", "coin_age_all": "10k–100k",
             "coin_age_6mo": "10k–100k", "coin_age_3mo": "1k–10k", "coin_age_30d": "100–1k"}
  },
  "backed": true,
  "tipped_by": "5+ members",
  "tipped": "10+ members",
  "parked_held": "3+",
  "names_bought": "1+",
  "names_sold": "1+",
  "attested_sites": "3+",
  "active_sites_30d": "1+",
  "active_sites_90d": "3+",
  "settled_sites": "1+",
  "settled_counterparties": "5+",
  "dispute_free": true,
  "human_witnessed": 90,
  "human_costly": 55,
  "human_confidence": 90,
  "competence": [{"code": "software.web", "domain": "Software & IT", "subdomain": "Web development", "endorsed_pct": 60}],
  "pay_link": "https://app.mask.id/pay/hTgkxGkYyBWJow0KrTppBQ",
  "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.
• Ban the subject_id, not the account. It is stable for a member on your site: a member who revokes and later re-verifies receives the same subject_id, so a ban you keyed on it holds across revoke-and-rejoin. Getting a fresh one takes a whole new Mask.ID identity — the cost your tier gate sets.
• 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_index_tier": "trusted",
     "trust_score": 78, "real_person": 92, "recommend_pct": 95,
     "capital": {"pivx": {"unit": "PIV", "commitment": "1k–10k", "coin_age_all": "10k–100k"}},
     "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

Today, during the pilot, everything on this page is free and keyless — verification, webhooks, and the subject read. When API keys ship, pricing will meter monthly active verified members. The tier schedule, discounts, founding-site terms, and the free community tier live on the pricing page. Building against the API? We’d like to hear from you (Contact form in the footer) — early integrators get the founding-site terms.

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