Developer preview

BlockiD for developers

Add “Sign in with BlockiD” to any site — self-sovereign login with zero-knowledge age / KYC proofs. Standard OpenID Connect: any OIDC library works.

Libraries

Any OpenID Connect library (code flow + PKCE S256).

JavaScript SDK in the repository (not yet published); other languages planned. To verify ZK proofs yourself: npm i snarkjs

OpenID Connect

code + PKCE S256

Pairwise sub

unlinkable across sites

ZK proofs

age and KYC, no documents

Preview

apps registered by the team

Integrate in three steps

Standard OIDC. Private by default.

  1. 01Start the login (server)

    Create the client and an authorization URL. Save the code verifier, state and nonce in the session, then redirect.

    // illustrative - the same flow with any OIDC library
    const client = new BlockIdClient({
      issuer: process.env.BLOCKID_ISSUER,   // this site's origin
      clientId, clientSecret,               // omit secret for a public client
      redirectUri,
    });
    const { url, codeVerifier, state, nonce } =
      await client.createAuthorizationUrl({ scopes: ["openid", "zk_age_over_18"] });
  2. 02Handle the callback & verify

    Exchange the code and verify the ID token. sub is a pairwise pseudonym; age_over_18 is ReaperNet’s asserted answer.

    // illustrative
    const { idToken, accessToken } = await client.exchangeCode({ code, codeVerifier });
    const claims = await client.verifyIdToken(idToken, { nonce });
    // claims.sub, claims.age_over_18
  3. 03 · optionalVerify the ZK proof yourself (optional)

    Pin the issuer key and verify against your own policy — never trust anything embedded in the claim.

    // illustrative
    const info = await client.getUserInfo(accessToken, { challenge: state });
    const pinned = await client.issuerPublicKey();   // fetch once, pin
    const ok = await verifyZkClaim(info.verified_claims.age_over_18, {
      pinnedIssuerPublicKey: pinned, rpClientId: clientId,
      minAge: 18, expectedChallenge: state,
    });
Endpoints

Six endpoints. Nothing proprietary.

MethodPathPurpose
GET/.well-known/openid-configurationDiscovery
GET/.well-known/jwks.jsonES256 keys for id_token signatures and BlockiD share statements
GET/api/oidc/authorizeCode + PKCE S256; shows the consent screen
POST/api/oidc/tokenReturns id_token + access token
GET/api/oidc/userinfoScope-gated claims + ZK proofs; ?zk_challenge= binds a proof
GET/api/oidc/zk-issuerIssuer public key to pin
Scopes

Ask only for what you need.

openid

Required. A pairwise sub per site.

profile

Name and country.

email

Email and email_verified.

wallet

The user’s ReaperNet wallet address.

kyc

KYC level only — never the documents.

zk_age_over_18 · zk_age_over_21

A zero-knowledge age proof.

zk_kyc_verified

A zero-knowledge “KYC verified” proof.

Security checklist
  • Pin the issuer key from /api/oidc/zk-issuer; never trust an embedded issuerPublicKey.
  • Send a fresh challenge per request — it stops forwarding and replay.
  • Request only the scopes you need. Users see them and can revoke.
Register your app

BlockiD is issued by ReaperNet. During the developer preview, apps are registered by the team — contact us or use the developer console.

Check a BlockiD

Shares come with a statement you verify yourself.

  1. In your organisation's BlockiD app, open Check a BlockiD, pick what you ask for and show the code (it lives 5 minutes). Or scan the code a person shows you.
  2. The person sees your name — as a verified organisation only once your verification is approved — ticks what to share and approves with a fingerprint.
  3. You see the facts and can open each document once, within 10 minutes; its bytes must match the hash fixed at approval. The shared copy is erased afterwards, and the person can end the share at any time.
  4. Copy the signed statement and keep it: an ES256 JWS (typ blockid-share+jwt) naming exactly the shared facts, whether ReaperNet checked each one, and the SHA-256 of each document. exp is the end of the viewing window, not of the proof.

Today sharing runs in the BlockiD app; there is no server-to-server share API yet.

import { createPublicKey, verify } from 'node:crypto';

const [h, b, s] = statement.split('.');
const head = JSON.parse(Buffer.from(h, 'base64url').toString());
if (head.alg !== 'ES256' || head.typ !== 'blockid-share+jwt') throw new Error('not a share statement');

// fetch once and cache; pick the key the statement names
const { keys } = await (await fetch(ISSUER + '/.well-known/jwks.json')).json();
const jwk = keys.find((k) => k.kid === head.kid);
const genuine = verify('sha256', Buffer.from(h + '.' + b),
  { key: createPublicKey({ key: jwk, format: 'jwk' }), dsaEncoding: 'ieee-p1363' },
  Buffer.from(s, 'base64url'));

const claims = JSON.parse(Buffer.from(b, 'base64url').toString());
// claims.aud must be YOUR BlockiD (did); claims.sub = the person; claims.jti = the share
// claims.facts     = { [fact]: { value, checked } }
// claims.documents = [{ kind, sha256, checked }]  -> hash the file you opened and compare

Private login,
in an afternoon.