Identity access

Scopes

Scopes define the maximum information an application may request. They never bypass user consent, data availability, or UnifyID policy.

Enabling a scope only makes it eligible for a request. The user must still grant that scope during authorization before any corresponding information can be disclosed.

Scope catalogue

Risk describes the sensitivity of the requested information. “Attestable” means UnifyID can accompany the verified result with privacy-safe proof metadata; it never means raw evidence or biometric data is disclosed.

Scope dependencies

Document selection policy

Document access is configured in three layers. First select an issuing country, then one or more document types from that country’s live catalogue, and finally the exact fields your application may receive. New catalogue entries are never added to an existing application automatically.

Retrieve approved documents

List approved documents first, then retrieve one document using its opaque, application-specific reference. A reference is not a document number, differs between applications, and stops resolving when the document or consent is no longer shareable.

{
  "data": {
    "documents": [{
      "documentReference": "docref_opaque_application_value",
      "displayName": "NG Passport",
      "documentType": "passport",
      "issuingCountry": "NG",
      "validityStatus": "active",
      "verified": true
    }]
  }
}

{
  "data": {
    "documentReference": "docref_opaque_application_value",
    "displayName": "NG Passport",
    "documentType": "passport",
    "issuingCountry": "NG",
    "expiryDate": "2031-07-31",
    "validityStatus": "active",
    "verified": true,
    "verifiedAt": "2026-07-31T12:00:00.000Z",
    "maskedDocumentNumber": "•••• 7778",
    "proof": {
      "type": "UnifyIDAttestation",
      "attestationId": "attestation_public_reference",
      "schemaVersion": "1.0",
      "status": "issued",
      "proofHash": "privacy_safe_proof_hash"
    }
  }
}

Restricted document numbers

document_number_full is unavailable in Sandbox. Production access requires an active Production application, explicit user consent, a permitted document field, and administrative approval. Every successful disclosure is audited. Prefer document_number_masked whenever possible.

Unavailable and revoked information

UserInfo omits unavailable claims rather than inventing a negative value. Document endpoints reject missing scope with insufficient_scope, return 404 when an approved reference no longer resolves, and reject tokens whose consent has expired or been revoked. Your application must stop new processing after revocation and apply its retention or deletion obligations.

Compatibility alias

identity_verification_status remains accepted for compatibility with earlier integrations. New applications should request identity_verified. Do not request both.

Least privilege

Consent behavior

The consent page shows the actual requested scopes. Adding a scope later requires a new authorization request; existing grants do not silently expand.