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.

Two ways to integrate

The same member gets the same subject_id on your site from both flows, so a site can start with free Login and add Verify later without touching its accounts.

Log in with Mask.ID — the whole integration

1. Mint a single-use nonce, bind it to the visitor’s browser session, and send them to https://app.mask.id/login?c=<base64url(request)>:

   {
     "v": 1,
     "type": "login",
     "nonce": "d41d8cd98f00b204e9800998",
     "redirect": "https://your-site.example/maskid/return",
     "expires": 1765588800
   }

   No rp_user_id, no scopes — a login request that asks for data is refused. So is a redirect with a #fragment or a port.
2. Recommended: publish the paths you return to at https://your-site/.well-known/maskid-redirects as {"v": 1, "redirects": ["/maskid/return"]}. Mask.ID then refuses any request for your host (Login or a Verify redirect) that returns anywhere else, so an open redirector on your site can’t be used to carry a member’s sign-in off to someone else. No file means no restriction.
3. The member confirms on Mask.ID and returns to your redirect with ?maskid=<payload>.<signature>. The payload:

   {
     "v": 1,
     "type": "maskid.login",
     "subject_id": "msub_k5r2…",
     "shield_address": "ps1…",
     "kind": "individual",
     "standing": "established",
     "rp_host": "your-site.example",
     "nonce": "d41d8cd98f00b204e9800998",
     "issued_at": "2026-10-25T14:02:09Z",
     "expires_at": "2026-10-25T14:07:09Z"
   }

4. Verify the Ed25519 signature over the decoded bytes (the same key and routine as attestations), then check type, rp_host, your nonce (unused, and from this browser), and expires_at (two minutes). Find or create the account by subject_id and start your own session. You never learn a name — assign one or ask. Keep shield_address with the account: it is a shielded PIVX address made for your site alone, the same one on every sign-in, so you can refund, pay out, or let the member withdraw to it without ever asking for an address. standing is established once the member has cleared the real-person hurdle and new until then — hold new accounts in probation and let the next sign-in lift it. kind says individual or organization.

Test your verifier: add &test=1 to your deep link and the confirm screen offers deliberately broken answers — bad signature, wrong type, wrong site, expired. Your site should accept the valid one once and refuse everything else, including the same answer a second time or in another browser.

Quick start: maskid-example-login.js (Node 18+, zero dependencies) is the whole thing in one file: button, nonce binding, verification, accounts, log out. Run it, open localhost:8080, sign in.

<a href="https://app.mask.id/login?c=BASE64URL_REQUEST"
   style="display:inline-flex;align-items:center;gap:.55rem;background:#4530b3;color:#fff;
          padding:.6rem 1rem;border-radius:9px;text-decoration:none;font:600 15px system-ui">
  <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
       stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
    <path d="M3 7c0-1 1-2 2-2h14c1 0 2 1 2 2v5c0 5-4 8-9 9-5-1-9-4-9-9V7z"/>
    <path d="M8 11.5c.8 1 1.7 1.5 2.5 1.5M13.5 13c.8 0 1.7-.5 2.5-1.5"/>
  </svg>
  Log in with Mask.ID
</a>

Verify with Mask.ID — the Attestation API

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",
  "website": "acme.org",
  "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

Log in with Mask.ID is free for every site, forever — no key, never metered. The rest of this page is Verify with Mask.ID: today, during the pilot, it 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.