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
| Network | Self API | Check pages | Issuer DID (signs the result) | Status |
|---|---|---|---|---|
| Mainnet | https://api.self.ixo.earth (did:web:api.self.ixo.earth) | https://self.ixo.earth | did:ixo:entity:3ea2744791e5b8ce1ddd7d96c9fd27e7 | Available. Callers by arrangement |
| Testnet | https://api.test.self.ixo.earth (did:web:api.test.self.ixo.earth) | https://test.self.ixo.earth | did:ixo:entity:f45746b09949bda3808d02439e212dcb | Available. The only caller is the testnet Auth Hub (did:web:test.auth.ixo.earth) |
| Devnet | https://api.dev.self.ixo.earth (did:web:api.dev.self.ixo.earth) | https://dev.self.ixo.earth | did:ixo:entity:80f392610e8a128b4f4b1ed828dbeb7f | Available. 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
| Check | A pass proves | It does not prove |
|---|---|---|
| Liveness only | A live person did the video selfie on this check's page, within its 15 minutes | Who 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 DID | That 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
- 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.
- 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.
- 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.
- The person has 3 tries. This wasn't me stops the check, and nothing is approved.
- 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 accountdid:ixo:ixo1…whoseassertionMethodkey 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.
| Field | Rule |
|---|---|
requestId | Your 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 |
nonce | Yours, 22 to 86 base64url characters. Make it fresh and keep it: the result carries it |
compare | Optional, { "did": "<the person's DID>" }, for the credential comparison |
context | Optional, only if your entry allows a send: { "type": "send", "amount", "symbol", "network", "recipient" }, shown to the person in Self's words |
returnUrl | Optional, https, at most 512 characters, no fragment, on one of your listed origins |
channel | Optional, 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
}- Find the key.
GET https://api.self.ixo.earth/identity/v1/issuerlists Self's keys: use thepublicKeyJwkof the key whoseidequalskid. Or read the issuer DID's document on chain (assertionMethod). Ifkidis not in your cached copy, read it once more (Self may have rotated its key). Never pass on a failure. - Pin the issuer.
issmust be Self's issuer DID for the network. - Check the binding.
audis your DID,nonceandrequest_idare what you sent,jtiis thecheckIdyou got,expis in the future andiatis not more than 60 seconds ahead. The result lives 10 minutes after Self decided (exp=iat+ 600). - Check the outcome.
outcomeispassed. The signedoutcomedecides, never the JSONstatus. - For a comparison, also
subis the DID you asked about andcompareis exactlytrue. A result withcompare: falsenever approves a comparison, whatevercheckssays.reference.idis a hash that names the person's identity verification without revealing it, andreference.approved_atis when it was approved. - For a context,
context_sha256is the hex SHA-256 ofcanonicalJson(context). - 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.
reason | Meaning | What to do |
|---|---|---|
no_credential | The 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 wallet | The 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_finished | Self could not finish the check: a service stayed busy past Self's own retries. Nothing was decided about the person | Create a new check when the person wants to try again |
liveness_failed | The video selfie did not pass, after 3 tries | Create a new check if you allow another attempt |
face_mismatch | The live face did not match the photo on the ID | Final for this check |
reference_unavailable | Self could not use the ID's photo for the comparison | Create a new check later |
error | Kept in the format. Self no longer produces it | Treat 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
| Limit | Value |
|---|---|
| Checks per person | 10 an hour, across callers: 429 subject_limit |
| Checks per caller | Your daily cap: 429 caller_limit until the next UTC midnight |
| Creates per caller | Rate limited: 429 rate_limited |
| Reads | At most one every 3 seconds; 30 a minute per check |
| Link and each step | 15 minutes |
| Tries | 3 judged video selfies per check |
| Signed result | Valid 10 minutes after the decision |
| A finished check | Readable with its result for 24 hours, then status only |
Errors
Every error is { "error": { "code", "message", "retryable", "reference" } }.
| Status | code | When |
|---|---|---|
| 400 | bad_request | A missing or malformed field |
| 401 | unauthorized | Any fault in the invocation or its proof |
| 403 | caller_not_allowed | Your DID is not a listed caller |
| 404 | check_not_found | An unknown check, or another caller's check |
| 409 | request_conflict | The same requestId with another body |
| 429 | caller_limit, subject_limit, rate_limited | A limit above (Retry-After) |
| 503 | auth_unavailable | Self 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.