API reference

The /v1 API is what a customer’s backend calls with an API key: verification sessions, the directory, events, check, screening, exceptions and approvals. Every /v1 response carries Hira-Request-Id (req_ and 32 hexadecimal characters) and Cache-Control: no-store, and no /v1 door answers CORS. The /v1 routes carry no version: a response change reaches every caller when the server deploys.

Authentication

Every /v1 door reads the key from one header:

Authorization: Bearer hira_sk_test_…

A key is hira_sk_live_ in a live account or hira_sk_test_ in its sandbox account, then 43 base62 characters, an underscore and a 6-character CRC32 checksum, so a mistyped key is refused without a lookup. Keys are created under Administration › Developer › API keys and shown once. A missing, malformed, revoked or rotated-out key, or a locked account’s key, answers 401 api_key_invalid with one body for every case. An address that sends 30 requests with a missing or invalid key in one minute answers 429 to every request for the rest of that minute, a valid key’s included.

Rotating a key creates a new key with the same scopes and app; the old key keeps working for 7 days, then stops. Revoking a key stops it at once.

Scopes

A key reaches only the products ticked in its Scopes when it was created. Scopes are fixed once the key exists; a rotated key keeps them. A key without the door’s product answers 403 api_key_scope_missing; an account whose plan lacks the product answers 403 product_not_enabled.

Errors

A refusal answers a JSON envelope: error is a sentence for a person, code a stable word for a program, and param, present only when the refusal is about one request field, names that field (dotted below the root, such as simulate.outcome). A code stays as written and answers one status; its sentence may change. A later version may add a code, so a branch on code keeps a default arm.

{
  "error": "A link lasts between 10 minutes and 7 days.",
  "code": "expires_in_out_of_range",
  "param": "expiresIn"
}

The SDK retries 429, 500, 503 and a network error; every other code is final for that request. GET /v1/approvals/{id} answers its 404 as { "error": "Decision not found." } with no code.

Rate limits

Each key has its own one-minute windows, and an account’s keys share one more. A spent window answers 429 rate_limited with a Retry-After header in whole seconds, at least 1.

A sandbox account also creates at most 500 verification sessions per UTC day; the next answers 409 daily_quota_reached.

Idempotency

POST /v1/verification-sessions takes an Idempotency-Key header of 1 to 255 printable ASCII characters. The key is scoped to the account and the key’s source app, kept for 24 hours, and stored only once a create has passed every rule, so a refused create leaves it free for the corrected retry.

• The same key with the same body answers 201 with the original session, no url, and the header Idempotent-Replayed: true. The body is compared in canonical form, so reordered keys or changed whitespace still match.
• The same key with a different body answers 422 idempotency_key_reused.
• Two creates racing on one key make one session; the second answers as a replay.

The SDK sends a key with every create and reuses it on its own retries. /v1/check and /v1/events carry their key in the event envelope instead, and the directory creates use customerRef as theirs.

Session object

Create, list, cancel, links and simulate answer the session in this shape. Words in an enumerated field may grow in a later version.

GET /v1/verification-sessions/{id} adds:

No session answer carries the url (outside create and /links), the expected details, a name, a date of birth, a document number, an image or a consent’s text.

POST /v1/verification-sessions 201 · scope verification · 16 KiB

Opens a session on a hosted program of the key’s account. Today a sandbox key alone creates: a live key answers 403 engine_not_connected, “Live verification sessions open once an engine is connected. Sessions are created in the sandbox account with a test key.” The body is strict: a field not listed answers 400 unknown_field.

Header Idempotency-Key, optional; see Idempotency. Answers 201 with the session and its url. Refusals, in the order a create meets them: 400 request_invalid, unknown_field, field_invalid (a body that does not bind); 403 product_not_enabled, engine_not_connected; 400 field_required, customer_ref_invalid, customer_ref_personal_data, expected_details_invalid (a control character), expires_in_out_of_range, metadata_invalid, field_invalid (simulate.outcome), return_url_invalid, return_url_origin_not_allowed, idempotency_key_invalid; 422 idempotency_key_reused; 404 program_not_found; 400 expected_details_invalid and field_invalid (the details’ or the applicant’s shape); 403 account_suspended; 409 program_not_active, daily_quota_reached, party_kind_mismatch, party_unavailable; 503 service_unavailable (the party changed while it was being registered; send the request again); 400 expected_details_required.

GET /v1/verification-sessions/{id} 200 · scope verification

The session with its detail fields. Past its deadline a session reads expired or abandoned once the minute sweep has stamped it. Refusal: 404 session_not_found, “No verification session of this account has that id.” A plan without Identity verification still answers this read.

GET /v1/verification-sessions 200 · scope verification

The account’s sessions newest first, whichever door opened them, as { "object": "list", "data": [...], "hasMore": boolean }. No totals and no status filter.

At most one of customerRef, clientReference and programId, and never both cursors: else 400 filters_not_combinable. A malformed programId, limit or createdAfter, or a cursor that names no session of the account, answers 400 field_invalid naming it.

POST /v1/verification-sessions/{id}/cancel 200 · scope verification · 1 KiB

No body, or an empty one. Cancels a session that is created, in_progress, expired or abandoned; a canceled session answers unchanged. A suspended account still cancels. Refusals: 404 session_not_found; 409 session_state_invalid for completed (“This verification link has already been completed, so there is nothing to cancel.”) and error.

POST /v1/verification-sessions/{id}/links 200 · scope verification · 1 KiB

Mints a fresh applicant link and answers the session with its new url. Body optional: { "expiresIn": seconds }, 600 to 604800, 72 hours unset. The previous link stops working and the deadline moves. An expired session becomes created and an abandoned one in_progress, with seq raised and one verification_session.reopened event; an open session keeps its seq. A retry after a lost answer mints a second link to the same session.

Refusals: 404 session_not_found; 409 session_state_invalid for a completed, canceled, errored or redacted session, and for a session opened through a program’s shared link; 403 account_suspended; 404 program_not_found (the program is archived or not a verification program); 409 program_not_active (paused); 400 expires_in_out_of_range.

POST /v1/verification-sessions/{id}/simulate 200 · scope verification · sandbox · 1 KiB

Body { "outcome": "verified" | "failed" | "unable-to-verify" }. Concludes every remaining step of the session with that outcome through the recorder the hosted page posts to, one step at a time, so each step is staged, evaluated and settled as a walk’s is, with assurance simulated. A face step with no granted consent concludes unable-to-verify with every measure not run. Answers the session.

Refusals, in order: 404 session_not_found; 400 simulate_not_allowed on a live account (“simulate is accepted in the sandbox account alone.”); 400 field_invalid for another outcome (“outcome is one of ‘verified’, ‘failed’ or ‘unable-to-verify’.”); 409 session_state_invalid when the session is not created or in_progress or is past its deadline (“This session is not open, so its steps cannot be simulated.”); 403 account_suspended; 404 program_not_found when the session’s program is archived or not a verification program; 409 program_not_active when it is paused (“This session’s program is paused, so its steps cannot be simulated.”).

Webhooks

Endpoints are registered in the console under Administration › Developer › Webhooks, on live and sandbox accounts alike; there is no /v1 door for them. An endpoint holds a URL, a description, an explicit list of event types (at least one) and the API version 2026-10-01. An account holds at most 10 endpoints, disabled ones included. An endpoint is created enabled, and its signing secret, hira_whsec_ and 32 random bytes, is shown once at create and at each roll. Send test event posts a test delivery and shows the receiver’s answer.

An endpoint URL is https on port 443, with no user name, password or fragment, at most 2048 characters, and not under a Hira domain. Redirects are never followed. Every address the name resolves to is checked at create, at a URL change and at every attempt, and private and special-purpose addresses are refused.

A session moving to error sends no event. The body is the same bytes on every attempt and resend:

Each delivery is a POST with Content-Type: application/json, User-Agent: Hira-Webhooks/1.0, Hira-Event-Id (the body’s id), Hira-Test-Webhook: true on a test send, and the signature:

Hira-Signature: t=1760242743,v1=5f2b…

t is unix seconds and each v1 is the hex HMAC-SHA256, keyed by the signing secret, over t, a dot and the raw body. Each attempt carries a fresh t and signature. For 24 hours after a secret roll both secrets sign and the header carries two v1 values. constructEvent(rawBody, header, secret, { tolerance, now }) in @hira/sdk verifies it and throws HiraSignatureError, whose reason is malformed_header, no_signature, bad_signature, timestamp_outside_tolerance or bad_tolerance. The tolerance is 1 to 600 seconds, 300 unless set, and cannot be turned off; now is the clock it is held to, a function answering milliseconds since the epoch, Date.now unless set.

Retries. A delivery counts when the receiver answers 2xx within 10 seconds; a 3xx, any other status, a timeout or a refused address is a failed attempt. A live account’s delivery is tried at once, then after 1 m, 5 m, 30 m, 2 h, 6 h, 12 h and 24 h three times, about 92 h 36 m in all, each wait varying by up to 10 percent; it then reads failed. A sandbox account’s is tried three times within an hour. An endpoint with seven days of only failures is disabled with a reason, and the account’s administrators and owners are told. Deliveries are not ordered: read the session through the API, and drop an event whose data.seq is below the last one applied for that session. Hira’s sending addresses are not published; trust a delivery by its signature.

Directory

Registers the account’s users and businesses as parties. Scope directory, create window. A key writes parties and reads none. Both bodies are strict: a field not listed, vendorRef included, answers 400 unknown_field and writes nothing.

POST /v1/directory/users 200

POST /v1/directory/businesses 200

Both answer a receipt and nothing else: { "id", "kind": "user" | "business", "customerRef", "created" }. A customerRef that already names a party of the same kind writes nothing and answers the same id with created: false; the values sent are not compared with the stored party. Refusals: 400 unknown_field and request_invalid; 400 field_invalid for any field rule, a customerRef outside the customer-reference rule included (the sentence says which); 403 product_not_enabled (“This account’s plan does not include the Directory API. Contact Hira to enable it.”); 409 party_kind_mismatch (“The customerRef already identifies a party of the other kind. One reference names a user or a business, never both.”); 503 service_unavailable when the party changed mid-registration and nothing was written. The SDK retries transient failures of a directory create only when a customerRef is set.

Events

POST /v1/events records activity after it happens. Scope monitoring, ingest window, 8 MiB body, at most 1,000 events a batch; a successful batch answers 202 with no body. Nine types are accepted. Each payload below is in addition to the common fields; unknown payload fields are kept on the event as sent. The required marks are the SDK’s types; the server enforces the envelope and the common-field rules. A batch with one refused event is refused whole.

mint Approved minter · reconciliation

burn Approved minter

transfer Large outflow · list match · allowlist

payout Velocity · list match · allowlist

redemption Recorded

A requested and a settled event that share a correlationId share one case reference. No policy judges a redemption yet.

reserve.snapshot Reserve ratio

reserve.movement Reserved: accepted and kept as sent; no policy reads it yet

admin.action Privileged action

kyc.updated Reserved: accepted and kept as sent; no policy reads it yet

Common fields

Every event accepts these alongside its own payload. At the SDK call site all are optional: the SDK fills occurredAt and idempotencyKey when absent. On the wire the server requires idempotencyKey on every envelope.

identity.check.result is refused with 400 event_type_retired: “identity.check.result is no longer accepted. Verification steps are recorded by Hira’s hosted page.”

Wire format

The SDK builds this. A flush posts a batch of envelopes to the ingestion endpoint:

{
  "events": [
    {
      "id": "3f1c…a9",               // SDK-assigned uuid
      "type": "mint",
      "source": "sdk",
      "schemaVersion": "1",
      "occurredAt": "2026-07-02T04:15:22.000Z",
      "idempotencyKey": "mint_8812",
      "payload": { "amount": "250000.00", "asset": "USDX", "toAddress": "0x9f…", "authorizedBy": "minter-svc" }
    }
  ]
}

The request carries Authorization: Bearer <key> and x-hira-sdk: ts/0.2.0. A successful ingest answers 202 Accepted with no body. A refused batch answers 400 field_invalid with a sentence naming the event, such as “events[0]: chain ‘eth’ is not a chain Hira knows. Known chains: …”.

POST /v1/check 200 · scope monitoring · 64 KiB

Asks before an action moves. The body is one event envelope, the shape a later /v1/events item of the same action would take. The answer is recorded: a breach raises a case as the executed action would, and a clean check is recorded as an allow. The proposed action is never stored as an event.

The same idempotencyKey with the same body answers the recorded answer, which is how a caller polls a Hold; the same key with another body answers 400 field_invalid. identity.check.result answers 400 event_type_retired.

GET /v1/screening/address/{address} 200 · scope monitoring

Screens one address against the lists the account maintains. An 0x address of 40 hex digits in any casing is lower-cased; any other, such as base58, is kept exactly. Each answered call is billable; refusals are not.

GET /v1/exceptions · GET /v1/approvals 200 · scope monitoring

GET /v1/exceptions answers the latest cases raised by the programs subscribed to the key’s source app, newest first, at most 50: { total, totalCapped, hard, items }, each item { id, outcomeType, title, triggerReason, sourceType, sourceEventReference, triggeredAt } with outcomeType HardBreach or SoftBreach. A full page sets totalCapped: true, total is then a floor and hard is null. The SDK has no method for it.

GET /v1/approvals answers the decisions recorded on the key’s streams, at most 50: { total, totalCapped, pending, items }. ?status= narrows to pending, approved, declined, superseded, withdrawn or expired; any other word answers 400 field_invalid. Each item is { id, status, declineType, reason, reference, exceptionId, origin, requestedAt, decidedAt, expiresAt }, with declineType retry or final and origin detective or preventive. pending is stated only when the page holds every waiting decision, else null. GET /v1/approvals/{id} answers one item, and 404 for an id outside the key’s scope. An account without the Approvals API answers 403 product_not_enabled. In the SDK: hira.approvals.list({ status }) and hira.approvals.get(id).

POST /v1/reset clears a sandbox source app’s stream data (its events, the exceptions they raised and wallets nothing else holds) and answers { exceptions, events, wallets }. It runs in Development and Demo environments alone; elsewhere, or for an app that is not a sandbox app, it answers 404.

Client surface

new Hira(config) creates a client. It throws without an apiKey, on an endpoint that is not https (plain http on localhost, 127.0.0.1 and [::1] alone) or that carries a user name or password, and on a hira_sk_ key where a DOM or a web worker is present. Construct one per process and reuse it.

hira.verificationSessions: create(input, { idempotencyKey?, signal? }), get(id, { signal? }), list({ customerRef?, clientReference?, programId?, createdAfter?, limit?, startingAfter?, endingBefore?, signal? }), cancel(id, { signal? }), createLink(id, { expiresIn?, signal? }) and simulate(id, { outcome }, { signal? }). Each throws HiraError on a refusal, with the server’s code.

hira.directory.users.create(input) and hira.directory.businesses.create(input) answer the receipt and throw HiraDirectoryError.

constructEvent(rawBody, header, secret, { tolerance?, now? }), exported on its own and as hira.webhooks.constructEvent, verifies a webhook delivery with no API key and throws HiraSignatureError.

hira.check(type, payload, { signal? }) answers the check and a poll() that asks again under the same key; it throws HiraCheckError. hira.screen(address, { signal? }) answers the screening and throws HiraScreeningError. hira.approvals.list() and .get(id) throw HiraApprovalsError. Every error class extends HiraError, which carries status, code, param, retryable and requestId.

hira.track(type, payload): void enqueues an event, never blocks and never throws; payload is typed to type. The background timer starts with the first track(). hira.flush() sends what is buffered; with the default failOpen: true it resolves even when a batch was dropped. hira.shutdown() flushes, then stops the timer.

Each awaited call takes a signal: an abort or AbortSignal.timeout(ms) ends the call with the caller’s own error, never retried and never a HiraError.