Proof API

The proof APIs expose current proof state and online verification with optional one-time consumption. Combine local signature verification with online checks for current revocation and consumption state.

Verify before execution

The relying-party backend must already know its expected issuer, tenant, environment, audience, action key, and locally computed action hash. Obtain those values from trusted configuration and the original pending business request. Retain those independent expectations throughout challenge resumption and verification.

Use the Node verifier for local checks, then call the online verification operation with the same action expectations and consume: true. The server performs a scoped state check and conditional consumption. consume: false checks status; consume: true performs the conditional single-use consumption required before execution.

Respect the transaction boundary

If consumption fails or its response is ambiguous, keep the operation unexecuted until your application reconciles its durable request state. For an already-consumed proof, inspect the existing attempt in your durable request ledger. GrayPass consumption and your business database are separate transactions.

Raw proofs are sensitive short-lived authorization artifacts. Keep them out of URLs, analytics, support messages, and general logs. Use trace or proof identifiers for diagnostics when sufficient.

Read Proofs and verification for key handling and failure reasons and Integration for application recovery. The operations below document proof state and online verification.

GET /api/v1/proofs/{jti}/status

Look up whether a proof is active, consumed, revoked, expired or unknown in this environment.

Credential: Server credential.

Inputs: Use a proof id obtained from a trusted trace or verified proof.

Effect and retry behavior: Read-only snapshot of proof state. Consume the proof through the verification operation to reserve its single use; state can change between lookup and consumption.

Parameters

Name / location	Required	Meaning, type and constraints
`jti` (path)	Yes	Proof identifier from a trusted authorization trace or verified proof. string

Responses

HTTP status	Meaning	Body
`200`	Proof id and active, consumed, revoked, expired or unknown state.	application/json: `ProofStatus`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: Execute only after successful verification and consumption of an active proof within the expected tenant and environment. Unknown or inactive state keeps the operation pending.

Example

HTTP

GET /api/v1/proofs/proof_example/status

Response - HTTP 200:

{
  "jti": "proof_example",
  "status": "consumed",
  "expires_at": "2026-10-01T12:05:00Z",
  "revoked_at": null
}

POST /api/v1/verify

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

Credential: Server credential.

Inputs: Supply audience, action and independent action hash from the original request. Perform offline subject/tenant/environment checks first. The example intentionally sends an invalid proof to show refusal.

Effect and retry behavior: consume defaults false; true conditionally consumes an active proof. Consumption and the customer business transaction are separate; ambiguous results require reconciliation, never blind replay.

Request body

application/json; required. VerifyRequest.

Responses

HTTP status	Meaning	Body
`200`	valid flag with verified claims on success, or refusal reason on failure; both can use HTTP 200.	application/json: `VerifyResponse`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: HTTP 200 can contain valid:false for malformed, expired, mismatched, revoked, unknown or consumed proof. Inspect valid; a successful transport response alone is insufficient.

Example

HTTP

POST /api/v1/verify

JSON request

{
  "proof": "not-a-jws",
  "audience": "merchant-api",
  "expected_action": "payout.destination.change",
  "expected_action_hash": "0000000000000000000000000000000000000000000000000000000000000000",
  "consume": true
}

Response - HTTP 200:

{
  "valid": false,
  "reason": "malformed",
  "claims": null
}