---
title: "Verify and optionally consume a proof"
method: POST
path: "/api/v1/verify"
tags: ["canonical"]
---

# Verify and optionally consume a proof

`POST /api/v1/verify`

## Request

- Base URL: `https://app.graypass.org` (the document declares no server; this is the origin it was published from)
- URL: `https://app.graypass.org/api/v1/verify`
- Auth: HTTP bearer

Verify signature/binding/current proof state and optionally consume the proof once for the pending operation.

## Request body

- VerifyRequest: Online verification against expected action binding, with optional atomic one-time consumption.
  - `audience` string, required: Expected relying-party audience. It must be permitted by the action and independently known to the verifier.
  - `consume` boolean: Default false performs a state check. Set true immediately before the protected operation to attempt one-time consumption; it is a separate transaction from your business database.
  - `expected_action` string, required: Action key independently retained with the pending business request.
  - `expected_action_hash` string, required: 64-character SHA-256 hex action hash computed from the original server-held material, never learned from an unverified proof.
  - `proof` string, required: Compact JWS obtained through your trusted authorization workflow. First perform the documented offline and subject/tenant/environment binding checks.

## Response `200`

valid flag with verified claims on success, or refusal reason on failure; both can use HTTP 200.

- VerifyResponse: Verification result. HTTP 200 can still mean valid is false; never authorize based on transport status alone.
  - `claims` object, nullable: Verified proof claims when valid, otherwise null. Compare them with the application’s independent expectations.
  - `reason` string, nullable: Stable verification refusal reason when invalid, otherwise null.
  - `valid` boolean, required: True only when all online checks succeed and, if requested, one-time consumption succeeds.

## Other responses

- `422`: The canonical handler returns a Problem for invalid input; correct the request before retrying.

---

[API](https://skmtc.dev/graypass/apis/graypass-api.md) - [All operations](https://skmtc.dev/graypass/apis/graypass-api/llms.txt) - [OpenAPI document](https://skmtc.dev/graypass/apis/graypass-api/revisions/5f9ab64fdfdb?raw)