Verify API

Single endpoint to launch a wallet verification

POST /v1/verify spins up a session, returns a QR/deep link, and handles the full OpenID4VP handshake. You receive status changes via webhook and can poll /v1/verify/{id} at any time.

Request

POST /v1/verify HTTP/1.1
Host: api.nexiel.io
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "credential_types": ["age_attestation"],
  "scope": ["age_over_18"],
  "required_assurance_level": "substantial",
  "metadata": {
    "user_id": "user_123",
    "context": "onboarding"
  }
}

Immediate response

{
  "verification_id": "v_abc123",
  "status": "pending",
  "session_url": "https://nexiel.io/verify/abc123",
  "qr_code": "image/png;base64,...",
  "deep_link": "nexiel://verify/abc123",
  "expires_at": "2025-01-16T10:30:00Z"
}

Step 3: Render the QR

Returns an eIDAS/EUDI-compliant PNG encoding the `openid4vp://` payload.

GET /v1/verify/v_abc123/qr?size=360 HTTP/1.1
Host: api.nexiel.io
Authorization: Bearer <ACCESS_TOKEN>
Accept: image/png

Scales between 160–1024 px via the `size` query param and regenerates the QR on each request, keeping the nonce/current authorization request in sync.

Webhook payload

Signed with HMAC-SHA256 (`X-Nexiel-Signature`). Retries occur up to 5 times.

POST https://yourapp.com/webhooks/nexiel
X-Nexiel-Signature: t=1736947200,v1=...

{
  "verification_id": "v_abc123",
  "status": "verified",
  "checks": { "age_over_18": true },
  "assurance_level": "substantial",
  "credential_type": "age_attestation",
  "verified_at": "2025-01-15T10:30:00Z"
}

Step 2: Fetch OpenID4VP request

Wallet bridges, kiosks, or QR generators call this.

GET /v1/verify/v_abc123/openid4vp HTTP/1.1
Host: api.nexiel.io
Authorization: Bearer <ACCESS_TOKEN>

OpenID4VP response

Returns the authorization request object, nonce, QR/deep link references, and presentation definition derived from your policy.

{
  "verification_id": "v_abc123",
  "status": "pending",
  "expires_at": "2025-01-16T10:30:00Z",
  "deep_link": "eudi-wallet://verify?request=v_abc123",
  "qr_code_url": "https://cdn.nexiel.io/q/v_abc123.png",
  "authorization_request": {
    "response_type": "vp_token",
    "response_mode": "direct_post",
    "client_id": "https://verify.nexiel.io",
    "redirect_uri": "https://api.nexiel.io/v1/verify/v_abc123/callback",
    "nonce": "53b6ea29c56443ffa86e6c734f89f8f4",
    "presentation_definition": {
      "id": "pd_v_abc123",
      "input_descriptors": [
        {
          "id": "descriptor_v_abc123",
          "name": "Verification flow",
          "constraints": {
            "fields": [{ "path": ["$.credentialSubject.age_over_18"] }]
          }
        }
      ]
    }
  }
}

Use cases covered

• Fintech onboarding (KYC + AML evidence)

• Age-gated e-commerce (alcohol, gaming, adult content)

• Insurance underwriting & policy upgrades

• Rental and landlord onboarding with income/residency checks

• Healthcare provider authentication and prescription workflows

• Government digital services & benefits enrollment

• Staff ID verification for visitor access or contractors

• Gyms, student unions, and transport passes