# 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](/guides/dev/wallet-sends) 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](/guides/dev/credentials/overview).

## 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

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

```http
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.

```json
{
  "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

```http
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>
```

```json
{
  "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:

```json
{
  "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`.

| `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

```mermaid
flowchart LR
  APP["App or oracle"] -- "send request" --> HUB["Auth Hub"]
  HUB -- "create check: compare + send context" --> SELF["Self Liveness Check"]
  HUB -- "check url" --> APP
  P["Person"] -- "video selfie" --> SELF
  SELF -- "signed result (EdDSA)" --> HUB
  HUB -- "verified: start the send" --> CHAIN["Chains"]
```

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](/guides/dev/wallet-sends#every-send-to-another-address-needs-a-face-check).

## Related pages

<CardGroup cols={2}>
  <Card title="Send tokens from the Auth Hub wallet" icon="paper-plane" href="/guides/dev/wallet-sends">
    The sends that need this check, with their API and action card.
  </Card>
  <Card title="IXO Credentials" icon="id-card" href="/guides/dev/credentials/overview">
    Self's `IdentityLevel1` proof of identity and where it is kept.
  </Card>
  <Card title="Authentication" icon="key" href="/guides/dev/authentication">
    UCAN invocations and delegations.
  </Card>
  <Card title="What works today" icon="table" href="/status">
    Where each capability is available.
  </Card>
</CardGroup>
