# Wallet face check for verifiers

Before the secuveri Wallet shares an identity credential it can run a face check: a liveness selfie (screen-flash challenge, presentation-attack and deepfake detection) matched by secuveri against the portrait of the holder's secuveri credential, which secuveri verifies first (issuer signature, status list, holder binding). As an OpenID4VP verifier you can require this check and verify that it happened for your request. The wallet cannot fake it: the attestation comes from secuveri, signed with the key published at `/.well-known/jwks.json`, never from the wallet.

### Ask for it

Add `"secuveri_face_check": "required"` to your signed request object. The wallet runs the face check whenever it is present, for any credential you ask for; it always runs it before sharing a `secuveri-passport`. Request the `portrait_sha256` claim of the `secuveri-passport` credential in your DCQL query so you can tie the face check to the person, for example:

```shell
{
  "client_id": "decentralized_identifier:did:tdw:…:verifier.example",
  "nonce": "n-0S9fX2Kq",
  "response_type": "vp_token",
  "response_mode": "direct_post.jwt",
  "secuveri_face_check": "required",
  "dcql_query": {
    "credentials": [
      {
        "id": "passport",
        "format": "dc+sd-jwt",
        "meta": {
          "vct_values": [
            "https://trust.secuveri.com/vct/secuveri-passport"
          ]
        },
        "claims": [
          {
            "path": [
              "given_name"
            ]
          },
          {
            "path": [
              "family_name"
            ]
          },
          {
            "path": [
              "portrait_sha256"
            ]
          }
        ]
      }
    ]
  }
}
```

The wallet binds the face check to your request object's `nonce` and your `client_id`, exactly as you sent them. If the face check fails or cannot run, the wallet does not send the presentation.

### Fetch and check the attestation

After you received and verified the presentation, fetch the attestation with the same nonce and client_id. It answers `202` while the selfie is still being checked, `404` when no face check was bound to your request, `409` when it was not approved, and `410` once fetched. Only an approved face check yields a JWT, and only once.

```shell
curl -G https://api-verify.secuveri.com/v1/face-check/attestation \
  --data-urlencode "nonce=n-0S9fX2Kq" \
  --data-urlencode "client_id=decentralized_identifier:did:tdw:…:verifier.example"
```

```shell
{
  "header": {
    "alg": "ES256",
    "typ": "secuveri-face-check+jwt",
    "kid": "<kid from /.well-known/jwks.json>"
  },
  "payload": {
    "iss": "https://api.secuveri.com",
    "aud": "decentralized_identifier:did:tdw:…:verifier.example",
    "iat": 1795082400,
    "exp": 1795082700,
    "jti": "0b8f4f5e-3c2a-4d1b-9e7f-6a5c4b3d2e1f",
    "nonce": "n-0S9fX2Kq",
    "face_check": {
      "verdict": "APPROVED",
      "liveness_method": "secuveri_selfie_flash_challenge",
      "checks": [
        "liveness",
        "deepfake",
        "face_match"
      ],
      "portrait_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "completed_at": "2026-11-19T09:59:30.000Z",
      "reference": {
        "type": "secuveri_credential",
        "issuer": "did:webvh:…:trust.secuveri.com:dids:issuer",
        "vct": "https://trust.secuveri.com/vct/secuveri-passport"
      }
    }
  }
}
```

- Verify the ES256 signature with the key from `/.well-known/jwks.json` whose `kid` matches, and require `typ` `secuveri-face-check+jwt`.
- `iss` is `https://api.secuveri.com`, `aud` your client_id, `nonce` the nonce of this request, and `exp` not passed.
- `face_check.verdict` is `APPROVED`.
- `face_check.portrait_sha256` equals the `portrait_sha256` claim of the secuveri credential in the presentation. This ties the live face to the credential you received; without the match, the attestation only shows that someone completed a face check.

secuveri customers can read the same verdict with their API key: `GET /face-check/attestation/{nonce}?client_id=…` through the verification API. For an approved wallet face check its answer carries the same JWT in `attestation`. Both routes share one single-use attestation. The JWT holds no personal data except the portrait hash; it carries no secuveri session id.
