Verification policies

A verification policy defines what a presentation must prove. You name a policy when starting a verification; DiligenceID turns it into the protocol request.

List

curl -sS "$DILIGENCE_BASE_URL/v1/verification-policies" \
  -H "Authorization: ApiKey $DILIGENCE_API_KEY"

Scope: verification-policies.read.

Read one

curl -sS "$DILIGENCE_BASE_URL/v1/verification-policies/verified-employee" \
  -H "Authorization: ApiKey $DILIGENCE_API_KEY"

Scope: verification-policies.read. Policies are addressed by the policyIdentifier you chose — internal references are never required from, or exposed to, a public caller.

Create

curl -sS -X POST "$DILIGENCE_BASE_URL/v1/verification-policies" \
  -H "Authorization: ApiKey $DILIGENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "policyIdentifier": "verified-employee",
        "displayName": "Verified employee",
        "organisationReference": "acme-ltd",
        "credentialConfigurations": ["ccr_example"],
        "requireActiveCredentialStatus": true,
        "requireHolderBinding": false
      }'

Scope: verification-policies.manage. Returns 201.

Field	Required	Notes
`policyIdentifier`	yes	Your stable identifier; this is what you name when verifying
`displayName`	yes	Shown to the holder as the purpose of the request
`organisationReference`	yes	The organisation the policy belongs to
`credentialConfigurations`	yes	The `configurationReference` values a presentation may satisfy
`requireActiveCredentialStatus`	no	Default `true` — a revoked credential fails
`failClosedOnStatusFailure`	no	Default `true` — if status cannot be checked, fail rather than accept
`requireHolderBinding`	no	Default `false`
`maximumCredentialAgeSeconds`	no	Reject credentials older than this
`activate`	no	Default `true` — created and activated in one call

Pass "activate": false to leave the policy in Draft. A Draft policy cannot start a verification.

Suspend and reactivate

curl -sS -X POST "$DILIGENCE_BASE_URL/v1/verification-policies/verified-employee/suspend" \
  -H "Authorization: ApiKey $DILIGENCE_API_KEY"

Scope: verification-policies.manage.

A suspended policy cannot start new verifications — an attempt returns 400. Verifications already in flight are unaffected. reactivate reverses it.

Suspending is the right tool when a policy is wrong or a credential programme is paused; it is reversible, unlike credential revocation.

Defaults worth understanding

requireActiveCredentialStatus and failClosedOnStatusFailure both default to true, which means a credential whose status cannot be confirmed is rejected rather than accepted. That is the safe default, and it means an outage in a status endpoint surfaces as verification failures rather than as silently weakened checks.

Not yet available

Claim constraints and issuer pinning exist in the underlying policy model but are not yet in the public create request. A policy created through /v1 accepts any trusted, active issuer currently authorised for the named credential configurations. Use Diligence Admin where you need narrower rules.

Edit this page on GitHub