POST
/
v1
/
verifications
Create a verification
curl --request POST \
  --url https://sandbox.authbound.io/v1/verifications \
  --header 'Content-Type: application/json' \
  --header 'X-Authbound-Key: <api-key>' \
  --data '
{
  "policy_id": "pol_age_over_18_authbound_v1",
  "provider": "auto",
  "provider_options": {
    "eudi": {
      "expected_origins": [
        "https://merchant.example"
      ],
      "authorization_request_scheme": "eudi-openid4vp",
      "authorization_request_uri": "<string>",
      "strip_trusted_authorities_for_wallet": true,
      "verifier_attestations": [
        {
          "format": "jwt",
          "data": "<string>"
        }
      ]
    }
  },
  "customer_user_ref": "<string>",
  "metadata": {},
  "return_url": "<string>"
}
'
{
  "id": "vrf_abc123",
  "object": "verification",
  "policy_id": "pol_age_over_18_authbound_v1",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "policy_hash": "<string>",
  "provider": "eudi",
  "client_action": {
    "data": "<string>",
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "verification_url": "<string>",
  "customer_user_ref": "<string>",
  "metadata": {},
  "terminal_at": "2023-11-07T05:31:56Z",
  "return_url": "<string>"
}

Authorizations

X-Authbound-Key
string
header
required

Server-side secret key header. Format: sk_live_* (production) or sk_test_* (testing).

Headers

Idempotency-Key
string

Unique key for idempotent requests

Maximum string length: 255

Body

application/json
policy_id
string
required

Policy to use for this verification

Maximum string length: 100
Pattern: ^pol_[a-z0-9_]+_v\d+$
Example:

"pol_age_over_18_authbound_v1"

provider
enum<string>
default:auto

Override provider selection

Available options:
auto,
eudi
provider_options
object

Provider-specific protocol options for the selected verifier. Omit them to use the policy profile's options: HAIP policies hand off with direct_post.jwt, profile haip, JAR by reference and a GET request URI, and AVP policies with plain direct_post. When given, eudi must name exactly that profile's set, optionally with the policy's authorization_request_scheme; any other set is a validation_error on provider_options.

customer_user_ref
string

Your reference for the end user

Maximum string length: 255
metadata
object

Custom metadata (stored, returned in responses)

return_url
string<uri>

Absolute http(s) URL, without userinfo or fragment, on an origin registered for the project (or localhost with a test key; a live key needs https and a public host) that the hosted verification page returns the user to.

Maximum string length: 2048

Response

Verification created successfully

id
string
required

Unique identifier

Example:

"vrf_abc123"

object
enum<string>
required
Available options:
verification
env_mode
enum<string>
required
Available options:
test,
live
status
enum<string>
required
Available options:
created,
awaiting_user,
awaiting_provider,
processing,
verified,
failed,
canceled,
expired
policy_id
string
required
Example:

"pol_age_over_18_authbound_v1"

created_at
string<date-time>
required
expires_at
string<date-time>
required
client_token
string
required

Opaque verification-scoped client token. Returned when creating a verification. Treat it as a bearer secret and do not depend on its internal format.

Example:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

policy_hash
string

SHA-256 hash of policy at creation time

provider
enum<string>

Selected provider ID

Available options:
eudi
Example:

"eudi"

failure_code
enum<string> | null

Reason for failure (only when status=failed)

Available options:
presentation_invalid,
credential_expired,
credential_revoked,
issuer_untrusted,
policy_not_satisfied,
processing_timeout,
provider_error,
user_declined,
wallet_error,
null
client_action
object

Action data for user to complete verification

verification_url
string<uri>

Link to the hosted verification page, returned on create when the installation has one, while the verification can still be handed to a wallet and its response mode is not dc_api.jwt. Its fragment carries the client token and the publishable key, so it is a bearer link. Redirect the user's browser to it; never show it as a QR code or write it to a log. For the wallet handoff, use client_action.data.

customer_user_ref
string

Your reference for the end user

metadata
object

Custom metadata

terminal_at
string<date-time> | null

When verification reached terminal state

return_url
string<uri>

The return_url given on create, which the hosted verification page returns the user to.

Maximum string length: 2048