Xodian Docs

#Overview

Xodian lets your app confirm that a user is one real person on a genuine phone, without learning who they are. No selfies, no ID uploads, no personal data.

The person confirms in the omni app. Your backend receives a signed id_token (ES256 JWT) that says:

• human: this is a real person on a genuine, unmodified phone
• sub: a private ID for this person that only your app sees, stable across visits
• level: how strong the evidence is (1 = device, 2 = established)
• uniqueness: whether this person is new to you, returning, or contested

Good fits

Airdrops and reward campaigns (one claim per person), game accounts and trials, community votes, and a cheap bot filter in front of full KYC.

Not a fit

Xodian is not identity verification. It does not tell you a person's name, age or country, and it does not satisfy KYC/AML obligations on its own.

#Quickstart (10 minutes)

You need a server that can keep a secret, and a web page or app to show the button. The sandbox is free and needs no sign-up.

1. Get a test key

   From the sandbox section of the home page, or by API. The secret is shown once; keep it on your server.

   COPY

   curl -X POST https://xodian.xode.net/v1/test/clients \
     -H "Content-Type: application/json" \
     -d '{"name":"Acme Airdrop","domain":"acme.example"}'
   
   # → {"clientId":"rpt_3f9a…","clientSecret":"osk_rpt_3f9a…_…",
   #    "test":true,"baseUrl":"https://xodian.xode.net","dailyQuota":500}

2. Open a session from your server

   reference is your own ID for this attempt (for example a claim ID). It comes back in the token as nonce.

   COPY

   curl -X POST https://xodian.xode.net/v1/sessions \
     -H "Authorization: Bearer $XODIAN_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"scope":["human"],"minLevel":1,"reference":"signup-42"}'

   COPY

   {
     "sessionId": "BQuIzVWtfYrpFA4_N4ZgzpLW",
     "pollToken": "CI_8JleZxedaAoDLo7Wg46vB",
     "expiresAt": 1791251375,
     "url": "https://xodian.xode.net/s/BQuIzVWtfYrpFA4_N4ZgzpLW",
     "deeplink": "xode://id?s=BQuIzVWtfYrpFA4_N4ZgzpLW",
     "scope": ["human"],
     "minLevel": 1,
     "test": true
   }

   Send the whole object to the browser. It contains no secret.

3. Show the button

   The widget draws the QR on desktop and a "Continue in omni" button on phones, polls the status, and calls you back.

   COPY

   <script src="https://xodian.xode.net/sdk.js"></script>
   <div id="verify"></div>
   <script>
     Xodian.button("#verify",
       () => fetch("/api/xodian/start", { method: "POST" }).then(r => r.json()),
       { onApproved: (s) => fetch("/api/xodian/finish?session=" + s.sessionId) });
   </script>

4. Answer it in the sandbox

   Test sessions show a Simulate panel inside the widget (approve, deny, reject, expire), or call the simulator API.

5. Fetch and verify the token on your server

   Read the session with your secret, then verify the idToken against the JWKS. See Verifying the token.

#Core concepts

Session

One verification attempt. Your server creates it; the person answers it in omni within 5 minutes (expiresAt). Every session ends in exactly one final state:

Assurance levels

Set minLevel per session. Below it you receive rejected and nothing else: no level, no signals.

Pairwise subject (sub)

Each app gets a different sub for the same person, so partners cannot join their data to track someone. Within your app it is stable: the same person gets the same sub every time, including after they move their wallet to a new phone. Several wallets on one phone get the same sub. Use sub as your key for "one per person".

Uniqueness

Scopes

human is always included. Add wallet to ask for the person's XODE wallet address; it is shared only if the person turns it on in omni, and your key must be enabled for it.

Reference and nonce

Whatever you pass as reference (up to 200 characters) is returned as the token's nonce. Check it, so a token issued for one attempt cannot be replayed for another.

#API reference

Base URL https://xodian.xode.net. JSON in, JSON out. Server calls authenticate with your client secret:

Authorization: Bearer osk_<clientId>_<random>

POST /v1/sessions

{
  "sessionId": "BQuIzVWtfYrpFA4_N4ZgzpLW",
  "pollToken": "CI_8JleZxedaAoDLo7Wg46vB",
  "expiresAt": 1791251375,
  "url": "https://xodian.xode.net/s/BQuIzVWtfYrpFA4_N4ZgzpLW",
  "deeplink": "xode://id?s=BQuIzVWtfYrpFA4_N4ZgzpLW",
  "scope": ["human"],
  "minLevel": 1,
  "test": true
}

url is what the QR encodes; deeplink opens omni directly on the same phone. Pass sessionId, pollToken, url, deeplink and expiresAt to the browser.

GET /v1/sessions/{id}

Server only. Returns the status; when approved it also returns idToken, sub and level. Only the client that created the session can read it.

curl https://xodian.xode.net/v1/sessions/BQuIzVWtfYrpFA4_N4ZgzpLW \
  -H "Authorization: Bearer $XODIAN_SECRET"

# approved →
{
  "sessionId": "BQuIzVWtfYrpFA4_N4ZgzpLW",
  "status": "approved",
  "expiresAt": 1791251375,
  "idToken": "eyJhbGciOiJFUzI1NiIs…",
  "sub": "oid_9f3c1a8be41d…",
  "level": 1
}

# rejected →
{ "sessionId": "…", "status": "rejected", "reason": "insufficient_level", "expiresAt": … }

GET /v1/sessions/{id}/status

For the browser. The session-scoped pollToken reveals only the state and, for final states, the reason. The widget calls this for you every 1 to 3 seconds.

GET https://xodian.xode.net/v1/sessions/{sessionId}/status?t={pollToken}

{ "sessionId": "…", "status": "pending", "expiresAt": 1791251375 }

Discovery and keys

GET https://xodian.xode.net/v1/.well-known/configuration

{
  "service": "Xodian",
  "issuer": "https://xodian.xode.net",
  "jwks_uri": "https://xodian.xode.net/v1/.well-known/jwks.json",
  "sessions_endpoint": "https://xodian.xode.net/v1/sessions",
  "scopes_supported": ["human", "wallet"],
  "levels": { "1": "device", "2": "established" },
  "id_token_signing_alg_values_supported": ["ES256"],
  "session_ttl_seconds": 300
}

Keys are ES256 (P-256). When we rotate, the previous key stays in the JWKS for a while, so tokens signed just before a rotation still verify. Cache the JWKS, and refetch when you see an unknown kid.

Errors

Errors are JSON: {"detail": "…"}, where detail is a message or an object with code and message.

#Web widget (sdk.js)

One small script with no dependencies. It works in any page and any framework.

<script src="https://xodian.xode.net/sdk.js"></script>

Xodian.button(target, getSession, options)

Renders a "Verify with Xodian" button into target (a selector or element). On click it awaits getSession(), which must return the session object from your backend, then opens the modal.

<script src="https://xodian.xode.net/sdk.js"></script>
<div id="verify"></div>
<script>
  Xodian.button("#verify",
    () => fetch("/api/xodian/start", { method: "POST" }).then(r => r.json()),
    { onApproved: (s) => fetch("/api/xodian/finish?session=" + s.sessionId) });
</script>

Xodian.open(session, options)

Opens the modal for a session you already have. Returns { close() }.

// Your own button, your own flow:
const session = await fetch("/api/xodian/start", { method: "POST" }).then(r => r.json());

const modal = Xodian.open(session, {
  onApproved: (s) => finish(s.sessionId),     // fetch the token on YOUR server
  onRejected: (s) => explain(s.reason),
  onDenied:   () => {},
  onExpired:  () => {},
  onClose:    () => {},                       // closed by the user
});
// modal.close() closes it from code.

Options

Wording and languages

The modal is English by default. Pass text to translate it or match your voice. Keys: title, subtitle, step1, step1m (mobile), step2, step3, openApp, noApp, secured, okTitle, okBody, deniedTitle, deniedBody, rejTitle, rejBody, expTitle, expBody, close. Missing keys fall back to English.

Xodian.open(session, {
  text: {
    title: "사람 인증",
    subtitle: "실제 사람인지 확인해요. 이름·번호·지갑은 공유되지 않아요.",
    step1: "omni 앱으로 스캔", step2: "공유 내용을 확인하고 승인", step3: "완료",
    close: "닫기",
  },
});

Native apps

// iOS / Android / Flutter: no QR needed on the same phone.
// Open the deeplink from the session your backend created:
openURL(session.deeplink)          // xode://id?s=…

// omni asks the person, then returns them. Your app polls your backend,
// which reads GET /v1/sessions/{id} with the secret.

#Xodian Connect (wallet)

Connect is Xodian as a web3 gateway: your site connects to a person's XODE wallet and asks for signatures, with no browser extension. The recovery phrase never leaves the omni app, and every request is shown there before anything is signed.

The shape of it: your backend opens a session, the person approves in omni (a QR on desktop, a deep link on the phone), your page receives a connect token once, and from then on the page asks for signatures with that token.

Opening a session

A live client opens the session from its backend, with its client secret, and hands the browser only sessionId and pollToken:

POST https://xodian.xode.net/v1/connect/sessions
Authorization: Bearer osk_<clientId>_<secret>
Origin: https://your-domain.example
Content-Type: application/json

{"clientId":"rp_…","scope":["human","wallet"],"minLevel":1}

Sandbox keys keep the browser-only path. A self-serve rpt_ key may open a session straight from the page, over your registered domain or http://localhost, because there it cannot pay: a real phone refuses a sandbox session, so it can never reach a real wallet. Such a session shows as unverified on the consent screen, and so does any session a live client opens without its secret.

The SDK

<script src="https://xodian.xode.net/connect.js"></script>

XodianConnect.init({ clientId: 'rp_…', chainId: 3417 });
const { address, evmAddress, sub, level } = await XodianConnect.connect();
XodianConnect.disconnect();

The connection (token, address, pairwise sub, level) is kept in the page's own localStorage and lasts 30 days. A 401 from a signing call means it was revoked or expired: the SDK clears it and reconnects.

Discovery works two ways. For EVM libraries the provider announces itself per EIP-6963 as XODE omni (rdns: net.xode.omni), so wagmi, RainbowKit and viem list it without anyone fighting over window.ethereum — pass init({ injectEthereum: true }) only if you want that slot filled and it is free. For polkadot-js apps the wallet is at window.injectedWeb3.xodian, with enable(), accounts.get() and a signer.

Provider methods

Errors worth handling

What omni refuses, and why

The signing screen is the security boundary, so it declines whatever it cannot explain to the person. Expect these, and treat them as correct:

• A message that is one of XODE's own reserved strings — anything beginning xode-. Those authenticate a wallet to XODE itself, so a site must not be able to ask for one.
• A call whose pallet and call index are not ones omni can check from the raw bytes, judged before any decoder is consulted.
• A batch wrapper. Reading what is nested inside one needs the full chain metadata, which the phone does not carry, so it is refused rather than approved on trust.
• Any balance transfer that is not one of the two it re-derives from the bytes itself, which is how a "transfer everything" call is kept out.
• Text containing bidi overrides or zero-width characters — rendered as hex with a warning, because such a line reads as something other than what it says.
• A long message, until the person opens it. Over roughly 400 characters or 8 lines it is collapsed and Approve stays disabled, so a challenge hidden below the fold cannot be signed by a tap. Keep sign-in messages short.

Receipts

Every signing decision is recorded in the Sentinel ledger and anchored on XODE, the same as a verification. A refusal carries the wallet's signature, so a receipt that says the person refused means the person; a request closed without one is recorded as a cancellation instead.

Limits

#Verifying the token

Always verify on your server. Never trust a status the browser reports.

Claims

{
  "iss": "https://xodian.xode.net",
  "aud": "rp_acme",
  "sub": "oid_9f3c1a8be41d02c7aa50e07b",
  "iat": 1791251090, "exp": 1791251690,
  "jti": "BQuIzVWtfYrpFA4_N4ZgzpLW",
  "nonce": "signup-42",
  "human": true,
  "level": 2, "level_name": "established",
  "uniqueness": "new",
  "verified_at": 1791251090,
  "receipt": "1791251090-a1b2c3d4",
  "wallet": "XqF4…"          // only with the wallet scope AND the person's consent
}

Checklist

1. Signature is ES256 and verifies against the JWKS
2. iss is https://xodian.xode.net and aud is your client ID
3. exp is in the future
4. nonce equals the reference you created the session with
5. jti has not been used before
6. In production, test is absent
7. level is at least what this action needs

import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(
  new URL("https://xodian.xode.net/v1/.well-known/jwks.json"));

export async function finish(sessionId, expectedReference) {
  const s = await fetch(`https://xodian.xode.net/v1/sessions/${sessionId}`, {
    headers: { Authorization: `Bearer ${process.env.XODIAN_SECRET}` },
  }).then(r => r.json());
  if (s.status !== "approved") return { ok: false, reason: s.reason || s.status };

  const { payload } = await jwtVerify(s.idToken, JWKS, {
    issuer: "https://xodian.xode.net",
    audience: process.env.XODIAN_CLIENT_ID,
    algorithms: ["ES256"],
  });
  if (payload.nonce !== expectedReference) throw new Error("token is for another session");
  if (payload.test && process.env.NODE_ENV === "production") throw new Error("sandbox token");
  await db.usedTokens.insertUnique(payload.jti);          // one use per token
  return { ok: true, person: payload.sub, level: payload.level,
           contested: payload.uniqueness === "contested" };
}

import os, requests, jwt   # pip install "pyjwt[crypto]" requests

JWKS = jwt.PyJWKClient("https://xodian.xode.net/v1/.well-known/jwks.json")

def finish(session_id, expected_reference):
    s = requests.get(f"https://xodian.xode.net/v1/sessions/{session_id}",
                     headers={"Authorization": f"Bearer {os.environ['XODIAN_SECRET']}"},
                     timeout=10).json()
    if s["status"] != "approved":
        return None
    key = JWKS.get_signing_key_from_jwt(s["idToken"]).key
    claims = jwt.decode(s["idToken"], key, algorithms=["ES256"],
                        audience=os.environ["XODIAN_CLIENT_ID"],
                        issuer="https://xodian.xode.net")
    assert claims["nonce"] == expected_reference
    assert not claims.get("test"), "sandbox token"
    return claims          # claims["sub"] is your key for this person

#Webhooks

Instead of polling, live keys can receive a POST when a session reaches a final state. Webhooks are set up with your live key (not available on self-serve test keys).

POST https://your-app.example/xodian/webhook
Content-Type: application/json
User-Agent: xodian-webhook/1
X-Omni-Signature: t=1791251090,v1=5f1c…e9

{"event":"session.approved","sessionId":"…","status":"approved",
 "expiresAt":1791251375,"idToken":"eyJhbGciOiJFUzI1NiIs…"}

# when the person removes your app in omni:
{"event":"grant.revoked","sub":"oid_9f3c1a8be41d02c7aa50e07b"}

Verify the signature

The header is t=<unix seconds>,v1=<hex>, where v1 = HMAC-SHA256(webhook secret, t + "." + raw body). Reject old timestamps to stop replays.

import crypto from "node:crypto";

// Use the RAW request body, exactly as received.
function verifyXodian(rawBody, header, secret /* whsec_… */) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  const ok = parts.v1 && crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(parts.v1.padEnd(expected.length)));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return ok && fresh;
}

Delivery

Respond with any 2xx within 8 seconds. Otherwise we try again, up to 4 attempts in total, with growing gaps. Deliveries can repeat, so handle them idempotently by sessionId, and still verify the idToken as usual.

#Sandbox

Test keys (rpt_…) are free and self-serve. Everything matches production except:

• Sessions are answered with the simulator, from the widget's Simulate panel or by API
• Tokens carry "test": true and a sub that starts with oid_test_
• No webhooks and no on-chain receipts
• 500 sessions per day per key; up to 5 new keys per network per day

Simulator

curl -X POST https://xodian.xode.net/v1/test/sessions/$SESSION_ID/simulate \
  -H "Content-Type: application/json" \
  -d '{"outcome":"approve","level":2,"persona":"alice","shareWallet":true}'

# outcome:    approve | deny | reject | expire
# level:      1 | 2                      (approve)
# persona:    any name; same persona → same sub
# uniqueness: new | returning | contested (optional, forces the value)
# reason:     insufficient_level | device_unverified | no_device | integrity_stale (reject)

The same persona always maps to the same sub, so you can test "one claim per person" and returning users. Approving below the session's minLevel produces a rejection, just as in production.

#Rejection reasons

A rejected session carries a reason. Show your users a neutral message; omni explains the details to them privately.

Treat unknown reasons as a generic rejection. New codes may be added.

#On-chain receipts

Every live decision, approve or deny, is written to the Sentinel ledger and anchored on the XODE chain every hour. The token's receipt claim is the handle for that record. You, or an auditor, can later prove that Xodian really made that decision at that moment and that nobody changed it afterwards.

GET https://xodian.xode.net/sentinel/receipt/1791251090-a1b2c3d4
GET https://xodian.xode.net/sentinel/anchors
GET https://xodian.xode.net/sentinel/verify.py     # independent verifier, standard library only

The ledger is public, so it never holds personal data: the subject is a hash, not the sub or the wallet.

#Security checklist

• The client secret lives only on your server. Never in a page, an app bundle or a repository
• Verify every token yourself: signature, iss, aud, exp, nonce, single-use jti
• Key one-per-person benefits on sub, not on wallet or email
• Decide what contested means for you before launch (accept, review or refuse)
• Use level 2 wherever money or votes are at stake
• Refuse test tokens in production
• Store only what you need: often sub and the date is enough

#Limits and keys

A session lives 5 minutes; a token 10 minutes. Live keys can be rotated on request. The old secret stops working the moment the new one is issued, so deploy the new one right away.

#For your users

You can link your users to this section. What they see:

1. Install omni

   Free on Google Play and the App Store. omni is the XODE app that runs a light node on the phone.

2. Scan or tap

   On a computer, scan the QR with the omni app. On the phone itself, tap "Continue in omni".

3. Check what is shared, then confirm

   omni shows which app is asking and exactly what it will receive. Confirming signs with the wallet key and the phone's hardware key.

4. Done

   The app learns that you are a real person, plus a private ID that only it sees. Never your name, number, balance or activity.

Managing apps

In omni, go to Settings → Xodian to see the apps you have verified with, your current level, and to remove an app. The app is notified when you remove it, but deleting data it already holds is up to that app; ask it directly.

"I was rejected"

omni shows the reason and how to fix it. Usually: use the store version of omni on an unmodified phone, open omni so it re-checks the device, or, for apps that ask for level 2, keep using omni on the same phone for a couple of weeks.

#FAQ

Changelog

• 2026-10-06 Moved to xodian.xode.net with short paths (/v1/…, /sdk.js, /s/<id>); issuer is now https://xodian.xode.net. Hand-off page in 4 languages.
• 2026-10-05 v1: sessions, levels 1–2, pairwise IDs, uniqueness, widget, sandbox and simulator, webhooks, on-chain receipts.