TRUST CENTER · VERIFIER GUIDE

Check the claim.
Understand the evidence.

Hybrid ID manages your identity credentials. Hybrid Explorer and the public proof APIs expose published signed records and their current status.

Configure verification for your application

Open Developer Apps, select your app’s Verification requirements, and save a policy version. Select required or optional checks, accepted evidence alternatives, maximum evidence age, verification purpose, privacy notice and requested retention periods. Saving requires your current authenticator code.

A saved policy defines a request, not a completed KYC check. Use the returned case state and collection_enabled capability to decide which customer actions to offer; never infer permission or a positive result from configuration.

Agent policy-management API

Use your owner-delegated developer credential with POST https://hybrid-id.com/api/developer/v1/applications. Send Authorization: Bearer <developer credential> from your backend. Do not use the app’s OIDC client secret or put credentials in browser code.

// applications:read; returns 25 versions and a next_offset cursor.
{"action":"verification-policy-list","client_id":"YOUR_APP_ID","offset":0}

// applications:write; returns policy_id. Retries of an identical
// application/version/body return the same ID; changed bodies are rejected.
{"action":"verification-policy-save","client_id":"YOUR_APP_ID","policy":{
  "name":"Customer onboarding","version":"1","requirements":[
    {"id":"identity_document","required":true,"accepted_evidence":["passport","national_id"]},
    {"id":"address","required":true,"accepted_evidence":["utility_bill","bank_statement"],"max_age_days":90},
    {"id":"sanctions","required":true,"accepted_evidence":[]}
  ],
  "data_handling":{
    "purpose":"Confirm identity for customer onboarding",
    "privacy_url":"https://your-application.example/privacy",
    "evidence_retention_days":90,"biometric_retention_days":0,
    "retention_start":"evidence_received","disclosure":"result_only",
    "reuse":"separate_consent","payer":"application"
  }
}}

The retention values above are examples, not a recommended compliance period. Set your application’s requirements. Evidence retention must be 1–3650 days. Biometric retention is 0 without biometric checks, otherwise 1 through the evidence-retention period. New requests require complete data_handling settings; create a new immutable version for older policies. The list response includes the supported requirement catalog. Biometric checks have prerequisites: face comparison requires an identity document, and liveness requires face comparison. Financial classification requires a jurisdiction and separately approved assessment rules. Configuration does not establish regulatory compliance.

Send a verification request

  1. Save a policy for your app, then enable verification requests in its app settings. Portal edits require fresh MFA; the agent update API accepts verification_enabled: true with applications:write.
  2. Request openid verification:request during Authorization Code with PKCE sign-in. The user approves the additional permission. Existing grants without this scope do not authorize requests.
  3. From your backend, authenticate with your app’s Basic client credentials and send the current user’s access token to the endpoint below. Never send an email address or a caller-selected identity as authority.
  4. Redirect the user to the returned continue_url. Hybrid Verify asks them to review the exact application and policy version. Their consent remains separate from sign-in approval.
POST https://auth.hybrid-id.com/verification/requests
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

operation=case-create&access_token=USER_ACCESS_TOKEN&policy_id=POLICY_ID&request_id=UNIQUE_REQUEST_KEY

// Read the same user's app-bound case with a current consented token:
operation=case-read&access_token=USER_ACCESS_TOKEN&case_id=CASE_ID

The response contains case_id, state, revision, policy_id, policy_digest, continue_url and collection_enabled. Keep credentials and tokens out of URLs and logs. Retrying the same app/request key for the same user and policy returns the existing case; reusing it for another user or policy is rejected.

Current states are consent_required, awaiting_evidence and cancelled. The collection_enabled field reports whether the provider permits canonical Data Vault document uploads and references. It is a service capability, not permission to collect documents, proof of an upload, or a verification result. Hybrid Verify checks its own current settings, the user’s consent, protection setup and Vault authority before accepting evidence. No processing charge is incurred by creating this request.

The user’s requests appear in Hybrid ID ID Verification & KYC and Hybrid Verify. No document access, cross-app disclosure or public identity publication is granted by this API. Purpose, privacy notice, retention periods and application sponsorship are pinned in the policy digest the user accepts. Document uploads are available through the protected Data Vault flow after the required approval. Document delivery to an application needs separate authorization. Use only a returned verification decision for its stated purpose; saving a policy does not authorize spending.

Hybrid ID verification and a recipient’s acceptance are separate decisions. Read the verification request contract.

Connected does not mean onboarding is complete

A bank or other application may accept a sign-in and still need additional verification. Keep those two states separate in your interface.

  1. Connection approved. The user approved your sign-in permissions. This does not authorize document collection or verify their identity.
  2. Additional approval required. Create a request for your saved policy version. Hybrid ID names your application and directs the user to review its purpose, evidence requirements, retention and result disclosure.
  3. Consent saved. The user explicitly approves that request in Hybrid Verify. Opening a link does not approve it; saved consent is not a passed check. Follow the current case state for the next supported step.

Users can find requests and connection updates in Access requests and their personal verification page. Approval for one application does not share documents with other applications.

Direct users to their request and its current status. A notification is not proof of verification; do not depend on email delivery to complete an application.

Onboarding & notification guide · Markdown

What a credential tells you

Manage the lifecycle

Public verification references

Replace CREDENTIAL_ID with the 32-character credential ID shown in the Trust Center. These public references do not require your Hybrid ID password, app client secret or developer credential.

PurposeReference
Human-readable recordhttps://hybrid-explorer.com/explorer/identities/CREDENTIAL_ID
Signed record and current statusGET https://hybrid-chain.com/api/explorer/identities/CREDENTIAL_ID
Issuer document and public keyGET /api/explorer/identities/issuer
Known-data challengePOST /api/explorer/identities/CREDENTIAL_ID/challenge
Generate presentationPOST /api/explorer/identities/CREDENTIAL_ID/presentation
Check presentation cryptography/statusPOST /api/explorer/identities/CREDENTIAL_ID/verify

The API returns a success envelope with the record under response. Keep the existing issuer identifier and credential URLs when verifying historical records; moving the management UI does not change their issuer.

Verifier acceptance checklist

  1. Obtain the credential from a trusted source and match its ID to the record you intend to verify.
  2. Resolve the expected issuer through a trusted, configured issuer reference. Do not trust an arbitrary public key embedded in an untrusted document.
  3. Validate the issuer signature over the canonical signed document using the declared suite. Check issuer identity, validity dates and current status. Fail closed for revoked, suspended, expired, unknown or unavailable status.
  4. Inspect each claim’s provenance and decide whether that assurance meets your application’s policy. Signature validity alone is not a KYC decision.
  5. For an interactive proof, bind acceptance to your own outstanding credential/claim/nonce request, expiration and intended context. Consume that request once; reject unrelated or replayed transcripts.

The public service’s issuer_signature_valid and verified fields are service evaluations. Independent cryptographic verification requires implementing or using the matching Hybrid suite, rather than trusting those booleans as an independent check.

The supported proof: matching known data

The deployed format is HybridZkKnownDataProof2026: randomized Pedersen commitments and a Schnorr opening proof, with an Ed25519-signed credential. It confirms that a value the verifier already possesses matches an issued commitment. It is not a general-purpose range-proof or arbitrary-predicate API.

// Known-data scalar; keep the cleartext on the verifier's side.
hex(SHA256("Hybrid-Chain-ZK-v1|" + claimId + "|" + value.normalize("NFC").trim()))

POST .../challenge
{"domain":"your-verifier.example"}
// Save returned uuid, nonce, expires and expected credential/claim locally.

POST .../presentation
{"challenge_uuid":"...","claim":"custom.example","message_scalar":"<hex>"}

POST .../verify
{"message_scalar":"<hex>","presentation":{...}}
// Also enforce your locally stored challenge/context/expiry and one-use policy.

Challenges expire after five minutes and are consumed during presentation generation. The verify endpoint checks cryptographic validity and current credential status; it does not maintain your application’s acceptance session. The domain label is context metadata, not proof that its sender controls that domain. Do not rely on the outer domain field alone for audience binding.

A scalar is derived from known data and may be guessable for low-entropy values. Keep scalars and transcripts out of analytics and logs. This proof service participates in generation; the flow is not evidence of a fully decentralized authentication server.

Implementation reference: Hybrid proof and signature format. Interoperability with generic W3C credential libraries must be checked for this custom suite.

Authentication and management are separate

OIDC sign-in grants the claims explicitly consented to by the user. It does not grant credential publication or revocation. App-registration agent credentials likewise cannot edit identity claims. Canonical owner mutations require a Hybrid ID account session, trust permission and fresh authenticator authorization.

Hybrid-Chain’s legacy claim and credential management actions now refer users to Hybrid ID and return 403 HYBRID_ID_MANAGEMENT_REQUIRED. Existing explorer records, read APIs, issuer-operated verification workflows and application compliance remain available.

SSO and developer integration guide · Identity API reference