Identity Verification (IDV)

Web3 Identity Made Simple

Think of IDV like OAuth for web3 - a familiar redirect flow that handles all the complexity of web3 identity 🔗. Just redirect your users to Royal, and we’ll handle everything: wallet setup, account creation 🔗, and delegation 🔗. When they return to your app, you’ll receive a verifiable identity token - use it to store the users Royal ID and you’re done!

Flow Overview

Loading graph...

sequenceDiagram
    participant App as Your App
    participant User
    participant Royal

    Note over App,Royal: One-time Setup Flow
    App->>User: Redirect to Royal IDV
    User->>Royal: Arrives at Royal

    rect rgb(240, 240, 240)
        Note over Royal: Royal Handles All Complexity
        Royal->>Royal: Check/Setup Wallet
        Royal->>Royal: Create/Verify Account
        Royal->>Royal: Setup Delegation
    end

    Royal->>User: Redirect back to app
    User->>App: Return with identity token

    Note over App: Store Royal ID

    Note over App,Royal: All Future Operations
    App->>Royal: Use stored Royal ID

Implementation Guide

1. Redirect Users to IDV

Construct the IDV URL with your registrar username (e.g., “yourApp”):

const idvUrl = new URL(`https://royal.io/idv/yourApp`);
idvUrl.searchParams.set("redirect_uri", "https://your-app.com/callback");
idvUrl.searchParams.set("state", sessionId);
idvUrl.searchParams.set("response_type", "token");

// Redirect user to idvUrl

URL Parameters

• redirect_uri: (Required) Must match one of your registered redirect URLs
• state: (Recommended) Session validation value, returned unchanged
• response_type: (Optional) Currently only supports “token”
• scope: (Optional) Returned unchanged in callback

2. Handle the Callback

Users return to your redirect_uri with the following query parameters:

• token: JWT containing identity information
• state: Your original state parameter
• delegated: “true” if delegation was successful

3. Token Verification

Get Royal’s public key from the well-known endpoint:

import jwt from "jsonwebtoken";

const ROYAL_JWKS_URL = "https://api.royal.io/idv/.well-known/jwks.json";

async function verifyToken(token, environment = "production") {
  // Fetch the current public key
  // this is a good place to memoize this result
  const response = await fetch(ROYAL_JWKS_URL);
  const jwks = await response.json();

  // Use the first key from the JWKS
  const publicKey = toPEM(jwks.keys[0]);

  return jwt.verify(token, publicKey);
}

app.get("/callback", async (req, res) => {
  try {
    const verified = await verifyToken(req.query.token);

    // Store the user's Royal ID for future use
    await db.users.update({
      id: currentUser.id,
      royalId: verified.ryl.sub.id,
    });

    // Success! User is now ready for web3 features
  } catch (err) {
    // Handle verification errors
  }
});

The library we use in this example for JWT, jsonwebtoken 🔗, expects to get the public key in PEM format, not JSON. You can use an online calculator 🔗 to get the PEM version.

Token Structure

The verified token contains:

{
  // Standard JWT claims
  "iss": "https://royal.io",
  "aud": "111", // Your registrar's Royal ID
  "sub": "109", // The user's Royal ID
  "iat": 1703030400, // Issued at timestamp
  "exp": 1703031000, // Expiry timestamp
  "jti": "unique-token-id",

  // Royal-specific data
  "ryl": {
    "aud": {
      "id": "111",
      "address": "0xa4d4...",
      "username": "yourApp"
    },
    "sub": {
      "id": "109",
      "address": "0xb8cb...",
      "username": "user_name"
    },
    "state": "your-state-value"
  }
}