Self Liveness Check

Confirm that a live person is present, and optionally that they are the person behind a DID's Self proof of identity: becoming a caller, creating a check, sending the person to it, verifying Self's signed result, outcomes, reason codes and limits.

The Self Liveness Check is a short video selfie a person takes on Self's own web page, on request from a service. Self signs the result, and the service verifies it before it acts. It proves that a live person was at the camera. With the optional credential comparison, it also proves that this person's face matches the photo on the ID behind the Self proof of identity of a given DID. Use it before an action that must be done by the person themselves, such as a payment out of their wallet. The Auth Hub uses it for every wallet send to another address.

Where it runs

NetworkSelf APICheck pagesIssuer DID (signs the result)Status
Mainnethttps://api.self.ixo.earth (did:web:api.self.ixo.earth)https://self.ixo.earthdid:ixo:entity:3ea2744791e5b8ce1ddd7d96c9fd27e7Available. Callers by arrangement
Testnethttps://api.test.self.ixo.earth (did:web:api.test.self.ixo.earth)https://test.self.ixo.earthdid:ixo:entity:f45746b09949bda3808d02439e212dcbAvailable. The only caller is the testnet Auth Hub (did:web:test.auth.ixo.earth)
Devnethttps://api.dev.self.ixo.earth (did:web:api.dev.self.ixo.earth)https://dev.self.ixo.earthdid:ixo:entity:80f392610e8a128b4f4b1ed828dbeb7fAvailable. The only caller is the devnet Auth Hub (did:web:dev.auth.ixo.earth)

The examples on this page use the mainnet host. On testnet and devnet, use that network's Self API and issuer DID from the table.

Self's identity verification itself, which issues the IdentityLevel1 proof of identity, runs on all three networks. See IXO Credentials.

What a pass proves

CheckA pass provesIt does not prove
Liveness onlyA live person did the video selfie on this check's page, within its 15 minutesWho the person is
With the credential comparison (compare)The live face matched the photo on the ID behind the valid Self proof of identity of that DIDThat the identity Self holds for the DID belongs to the account's owner

The second limit matters for a DID that has no proof of identity yet. Whoever first completes Self's identity verification for that DID is enrolled as its person. A party that holds the DID's key could enrol itself and then pass every comparison. Self applies no rule about this. A passed comparison carries reference, which names the identity verification behind it and when it was approved, so your service can apply its own rule, for example to hold an action when the identity is new.

What the person sees

  1. The person opens your link on a phone. The page names your service ("IXO asks you to confirm it's you"), says it takes about a minute, and, for a send, shows the amount, the network and the whole recipient address. They press Start and take a short video selfie.
  2. On a computer the page first shows a QR code to continue on the phone, because phone cameras work best, and Continue on this computer as the second choice. The computer then follows the check on the phone and shows how it ends.
  3. If a service Self relies on is busy, the page waits and asks again by itself for about 20 seconds, then says "We couldn't finish just now" and offers Try again on the same check. Busy tries do not count.
  4. The person has 3 tries. This wasn't me stops the check, and nothing is approved.
  5. When the check ends, the page sends the person back to your returnUrl, or tells them to go back to their chat.

The link works once, on the first device that opens it, and ends after 15 minutes. It needs no sign-in.

Privacy

  • Self returns no image, no score and no name to your service or to the person's page: only the outcome, a reason code and the signed result.
  • For the comparison, Self reads the photo on the person's ID in memory for that one comparison. It is never stored or logged.
  • Self's logs carry the check id and codes, never the person's DID, a nonce, a token or a score.
  • A finished check is readable with its result for 24 hours. After that the check's data is deleted and only its status remains.

Use it from your service

1. Become a caller

Ask IXO to list your service as a caller on mainnet. On testnet and devnet the network's Auth Hub is the only caller. Send:

  • your DID: a did:web:<host> with its Ed25519 key (Self pins the key and never fetches your document), or an account did:ixo:ixo1… whose assertionMethod key is on chain;
  • the name Self shows the person (1 to 40 characters);
  • a daily cap on checks, which is the spend control (there is no billing);
  • the origins you may send the person back to;
  • whether you will show a send on the page (context).

Until you are listed, every create is 403 caller_not_allowed.

2. Create a check

POST https://api.self.ixo.earth/identity/v1/liveness-checks
Authorization: Bearer <UCAN>
Content-Type: application/json

{"compare":{"did":"did:ixo:ixo1…"},"nonce":"u7Qw3rJ0b2l1Lw8x9pZkVg","requestId":"order-7f3c2a91","returnUrl":"https://app.example.com/checks/done"}

Send the body as canonical JSON: keys sorted at every depth, no spaces.

FieldRule
requestIdYour idempotency key, 1 to 128 of A-Z a-z 0-9 . _ : -. The same body again answers the same check (200); another body is 409 request_conflict
nonceYours, 22 to 86 base64url characters. Make it fresh and keep it: the result carries it
compareOptional, { "did": "<the person's DID>" }, for the credential comparison
contextOptional, only if your entry allows a send: { "type": "send", "amount", "symbol", "network", "recipient" }, shown to the person in Self's words
returnUrlOptional, https, at most 512 characters, no fragment, on one of your listed origins
channelOptional, lower case, for example whatsapp: the page then says "Go back to your chat"

The whole body is at most 16 KiB, and fields not in this table are refused.

The UCAN. An invocation issued by your DID, audience Self's DID (did:web:api.self.ixo.earth), exactly identity/liveness on ixo:identity, an expiry at most 5 minutes ahead, and the facts { "method": "POST", "path": "/identity/v1/liveness-checks", "body_sha256": "<hex SHA-256 of the body text>" }. Without compare it has no proof. With compare its one proof is the person's own delegation of identity/liveness on ixo:identity to your DID, signed with the person's key and valid at most 31 days: their consent. Without it the create is 401, and Self reads nothing about the DID.

{
  "checkId": "…",
  "url": "https://self.ixo.earth/c/…",
  "status": "created",
  "expiresAt": "2026-11-20T12:15:00.000Z"
}

A check is never decided at creation, so creating one tells you nothing about the person.

3. Send the person to url

Open it in the top window or a normal browser tab, never in a frame. It is a bearer link for 15 minutes. Send it only to the person.

4. Read the result

GET https://api.self.ixo.earth/identity/v1/liveness-checks/<checkId>
Authorization: Bearer <UCAN bound to {"method": "GET", "path": "/identity/v1/liveness-checks/<checkId>"}, no proof>
{
  "checkId": "…",
  "status": "passed",
  "reason": null,
  "updatedAt": "2026-11-20T12:03:30.000Z",
  "expiresAt": "2026-11-20T12:15:00.000Z",
  "result": "eyJhbGciOiJFZERTQSIsImtpZCI6…"
}

Poll no faster than every 3 seconds (30 reads a minute per check) until status is final: created, opened and in_progress are open; passed, failed, expired and cancelled are final. Only the service that created a check can read it.

5. Verify the signed result before you act

result is a compact JWS. Its header is { "typ": "liveness-result+jwt", "alg": "EdDSA", "kid": "<issuer DID>#<key id>" }. Its payload:

{
  "iss": "did:ixo:entity:3ea2744791e5b8ce1ddd7d96c9fd27e7",
  "aud": "did:web:app.example.com",
  "jti": "<checkId>",
  "request_id": "order-7f3c2a91",
  "nonce": "u7Qw3rJ0b2l1Lw8x9pZkVg",
  "sub": "did:ixo:ixo1…",
  "outcome": "passed",
  "compare": true,
  "checks": { "liveness": "passed", "credential": "passed", "face_match": "passed", "reference": "didit_document" },
  "reference": { "id": "<hex SHA-256>", "approved_at": "2026-11-12T09:41:07Z" },
  "iat": 1795621610,
  "exp": 1795622210
}
  1. Find the key. GET https://api.self.ixo.earth/identity/v1/issuer lists Self's keys: use the publicKeyJwk of the key whose id equals kid. Or read the issuer DID's document on chain (assertionMethod). If kid is not in your cached copy, read it once more (Self may have rotated its key). Never pass on a failure.
  2. Pin the issuer. iss must be Self's issuer DID for the network.
  3. Check the binding. aud is your DID, nonce and request_id are what you sent, jti is the checkId you got, exp is in the future and iat is not more than 60 seconds ahead. The result lives 10 minutes after Self decided (exp = iat + 600).
  4. Check the outcome. outcome is passed. The signed outcome decides, never the JSON status.
  5. For a comparison, also sub is the DID you asked about and compare is exactly true. A result with compare: false never approves a comparison, whatever checks says. reference.id is a hash that names the person's identity verification without revealing it, and reference.approved_at is when it was approved.
  6. For a context, context_sha256 is the hex SHA-256 of canonicalJson(context).
  7. Use it once.

The result has no vct, so it can never pass as a credential.

Handle the outcomes

reason is present only with failed.

reasonMeaningWhat to do
no_credentialThe DID has no valid Self proof of identity: none, one that expired or was revoked, or an approved one not yet saved to the person's Auth Hub walletThe person verifies their ID at Self (https://self.ixo.earth/verify/new). Self's page already offered Verify my ID. Then create a new check
not_finishedSelf could not finish the check: a service stayed busy past Self's own retries. Nothing was decided about the personCreate a new check when the person wants to try again
liveness_failedThe video selfie did not pass, after 3 triesCreate a new check if you allow another attempt
face_mismatchThe live face did not match the photo on the IDFinal for this check
reference_unavailableSelf could not use the ID's photo for the comparisonCreate a new check later
errorKept in the format. Self no longer produces itTreat as a failure

expired means the person did not finish within 15 minutes. cancelled means the person pressed This wasn't me. A check that did not pass never passes later.

Verify my ID without a sign-in

When a check ends no_credential, Self's page offers Verify my ID. Normally that starts Self's identity verification after a sign-in through the Auth Hub. A caller that IXO enables for identity links can instead send the person's own grants with the check (identity: their identity/link delegation to the caller, valid at most 30 minutes, and their consent that Self's credential is saved to their wallet). The page then opens the verification without a sign-in, and the proof of identity is saved to the person's Auth Hub wallet by itself. The Auth Hub is enabled for this; ask IXO if you need it.

Limits

LimitValue
Checks per person10 an hour, across callers: 429 subject_limit
Checks per callerYour daily cap: 429 caller_limit until the next UTC midnight
Creates per callerRate limited: 429 rate_limited
ReadsAt most one every 3 seconds; 30 a minute per check
Link and each step15 minutes
Tries3 judged video selfies per check
Signed resultValid 10 minutes after the decision
A finished checkReadable with its result for 24 hours, then status only

Errors

Every error is { "error": { "code", "message", "retryable", "reference" } }.

StatuscodeWhen
400bad_requestA missing or malformed field
401unauthorizedAny fault in the invocation or its proof
403caller_not_allowedYour DID is not a listed caller
404check_not_foundAn unknown check, or another caller's check
409request_conflictThe same requestId with another body
429caller_limit, subject_limit, rate_limitedA limit above (Retry-After)
503auth_unavailableSelf could not check whether the person's delegation was revoked. Try again

How it fits with wallet sends

The Hub is a caller like any other. It asks for the comparison against the sender's own DID, shows the send on Self's page through context, binds the check to the send through its nonce, and starts the send only after it verifies the signed result. Details: Send tokens from the Auth Hub wallet.