Docs · Verify

Verification quick start

`POST /v1/verify` launches an OpenID4VP session. You receive a session URL, QR, deep link, and webhook events when the wallet finishes. This page walks through auth, scopes, and best practices.

DC4EU use_case presets

Pass `use_case` when hitting `/v1/sessions/eudi/initiate` to auto-load the scope, policy, and metadata expected by the Digital Credentials for the EU (DC4EU) pilots. These align with the education (WP5) and social security (WP6) work packages described on the official DC4EU site.

DC4EU Education QEAA

use_case: dc4eu_education_qeaa · Work package: WP5

Qualified Electronic Attestation of Attributes for diplomas, professional qualifications, and student cards.

scope → legal_name, date_of_birth, citizenship, education.institution_name, education.programme_name, education.programme_level, education.qualification_status, education.qualification_issue_date, education.qualification_valid_to

DC4EU Social Security (PDA1 / EHIC)

use_case: dc4eu_social_security_pda1 · Work package: WP6

Portable Document A1 and European Health Insurance Card attributes for cross-border labour mobility.

scope → legal_name, date_of_birth, citizenship, social_security.number, social_security.member_state, social_security.coverage_start, social_security.coverage_end, social_security.ehic_number, employment.employer_name

Verification modes (GDPR-first)

• Gate (default): returns only decisions (e.g., over18/over21, credential_valid, not_revoked). Best for age-gated retail/clubs.
• Match: returns booleans + reason codes for provided inputs (e.g., name_match=false, reason=dob_mismatch). No raw PII by default.
• Data: allow-listed attributes only; enabled for approved tenants with regulated use-cases (CDD/KYC), documented necessity, tighter retention, and audit.

Suggested tenant tiers

• Tier 1 (default): Gate + Match only; no raw attributes returned.
• Tier 2 (approved): Data allowed for specific use-cases/fields (allow-list), short retention, stronger audit logging.

Request payload (Gate default)

POST /v1/verify
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "mode": "gate",
  "scope": ["age_over_18"],
  "callback_url": "https://example.com/webhooks/nexiel",
  "metadata": { "user_id": "123", "context": "age_gate" }
}

Gate returns booleans only; ideal for age/eligibility checks. Always request the minimum scopes for GDPR data minimisation.

Responses by mode

Gate (default)

{
  "verification_id": "v_abc123",
  "status": "verified",
  "decisions": { "over18": true, "not_revoked": true, "credential_valid": true },
  "assurance_level": "substantial",
  "verified_at": "2025-01-15T10:30:00Z"
}

Match (user input vs wallet)

{
  "verification_id": "v_abc123",
  "status": "verified",
  "matches": { "name": true, "dob": false },
  "reasons": { "dob": "dob_mismatch" },
  "assurance_level": "substantial"
}

Data (allow-listed, approved tenants only)

{
  "verification_id": "v_abc123",
  "status": "verified",
  "data": { "name": "Jane Doe", "address": "123 Main St, Dublin" },
  "assurance_level": "high"
}

Verify `X-Nexiel-Signature` (HMAC-SHA256). Retries fire up to 5 times with exponential backoff (first retry at 30s).

Auth & environment

• Obtain an OAuth2 client credentials token; scopes should include `verify:write`.
• Sandbox base URL mirrors production but points to test wallets. Use `NEXIEL_GATEWAY_TOKEN` on server-side pages.
• Rate limits: Starter 10 req/sec, Professional 100 req/sec, Enterprise custom.
• Mutual TLS is optional but recommended for high-risk relying parties.

Scopes & claims

• `name`, `address`, `citizenship` – identity claims from issuer.
• `age_over_18`, `age_over_21` – zero-knowledge booleans for gating.
• `employment_status`, `income_band` – pulled from employer-issued credentials.
• Always request the minimum scopes needed for GDPR data minimization.
• Data mode requires allow-listed fields per tenant policy; Gate/Match are default-safe.

Error handling playbook

• `VERIFICATION_TIMEOUT`: user never opened the wallet. Prompt them or fallback to ident.
• `USER_DENIED`: user rejected consent; surface alternate flows.
• `INVALID_SCOPE`: request only supported claims for the credential issuer.
• `PROOF_REPLAY` / `HOLDER_BINDING_MISMATCH`: treat as high-signal and alert security.

Next steps

Embed the SDK →Webhook signatures →