Verification Protocol

1. Overview

Cardless ID separates two distinct operations that happen at very different frequencies:

This is analogous to Web3 login (Sign-In with Ethereum): the site asks a question, the wallet proves something using an on-chain asset, and the site gets a signed, verifiable answer. The blockchain is the source of truth; the API is just a lightweight relay.

2. The JS Snippet

Integrators add age verification with a single script tag. No backend required.

<script src="https://cdn.cardlessid.org/verify/latest/cardlessid-verify.js"></script>
<div id="age-gate"></div>
<script>
  const verify = new CardlessIDVerify({
    minAge: 21,
    onVerified: function({ meetsRequirement }) {
      if (meetsRequirement) {
        // User is 21+ — grant access
      }
    }
  });
  verify.mount('#age-gate');
</script>

import { CardlessIDVerify } from '@cardlessid/verify';

const verify = new CardlessIDVerify({
  minAge: 21,
  onVerified({ meetsRequirement }) {
    if (meetsRequirement) {
      // grant access
    }
  },
});

verify.mount('#age-gate'); // renders QR code

3. Verification Flow

1. 1

   Snippet fetches a nonce

   On load, the snippet calls GET /api/v/nonce. The server returns a short-lived signed nonce (expires in 5 minutes). No database write happens — the nonce is a signed JWT the server can verify later without storing anything.

2. 2

   Snippet displays a QR code

   The QR encodes { nonce, minAge, returnUrl }. On mobile, a deep link opens the wallet app directly. The minAge is embedded in the QR — the user cannot modify it.

3. 3

   Wallet reads the credential from Algorand

   The wallet app queries Algorand directly — no Cardless ID server involved. It reads the credential NFT held by the user's wallet address, inspects the ARC-69 metadata, and checks whether the birthdate satisfies minAge. This is a read-only operation; no transaction is created and no gas is spent.

4. 4

   Wallet signs a proof

   If the credential exists and the age requirement is met, the wallet signs a proof with the user's Algorand private key:

   {
     "nonce":            "eyJ...",
     "walletAddress":    "XYZAQ5E3...",
     "minAge":           21,
     "meetsRequirement": true,
     "timestamp":        1744829470000
   }

   The private key never leaves the wallet. The signature proves the holder of that wallet address made this assertion.

5. 5

   Wallet submits proof to Cardless ID API

   The wallet POSTs the signed proof to POST /api/v/submit. The server verifies the nonce signature (stateless check), then stores nonce → signedProof in a TTL cache for 60 seconds. That's the only "storage" that happens — it evicts automatically and contains no personal data.

6. 6

   Snippet retrieves and delivers the proof

   The snippet polls GET /api/v/result/{nonce} every 1–2 seconds. Once found, it delivers the signed proof to the integrator's onResult callback. The integrator can verify the Algorand signature client-side or pass it to their backend.

4. Full Sequence Diagram

The Cardless ID API appears twice: once as a stateless nonce issuer, and once as a 60-second proof relay. It never queries Algorand. The integrator's backend is entirely optional.

5. The Signed Proof

The proof is the only thing that crosses the wire between the wallet and the integrator. It contains no personal data — only a boolean assertion and the wallet address.

{
  "payload": {
    "nonce":            "eyJhbGciOiJIUzI1NiJ9...",
    "walletAddress":    "XYZAQ5E3EQFWMH3MQVK2BX...",
    "minAge":           21,
    "meetsRequirement": true,
    "timestamp":        1744829470000
  },
  "signature": "base64url-encoded-ed25519-signature"
}

import { verifyProof } from '@cardlessid/verify';

const result = verifyProof(proof);

if (result.valid && result.payload.meetsRequirement) {
  // Age verified — ed25519 signature and timestamp confirmed
}

6. Scalability

Every component in the verification path is either stateless or ephemeral. There is no database bottleneck.

7. Security Properties

8. Partner Wallet Apps

Third parties may build wallet apps that are compatible with the Cardless ID verification protocol. Because the wallet is responsible for reading the on-chain credential and producing the signed proof, a malicious wallet could lie about the result.

Integrators who require stronger guarantees should independently query Algorand to confirm the wallet holds a valid credential issued by a registered issuer — regardless of what the wallet app claims. The wallet address in the signed proof is the lookup key.

9. Standards Compatibility

The Cardless ID verification protocol is designed to align with SIOPv2 (Self-Issued OpenID Provider v2) and OID4VP (OpenID for Verifiable Presentations) — the W3C and OpenID Foundation standards for decentralized identity presentation. This positions Cardless ID for interoperability with SSI ecosystem pilots including eIDAS 2.0 wallet programs.

The underlying infrastructure (stateless nonce, TTL cache proof relay) is unchanged between the custom flow and the SIOP-OID4VP flow. Only the message format changes — from a custom JSON proof to a standard Verifiable Presentation.

Related Documentation