---
title: "Verify an x401 principal-identity presentation"
method: POST
path: "/api/x401/verify"
tags: ["Verification Records"]
---

# Verify an x401 principal-identity presentation

`POST /api/x401/verify`

## Request

- Base URL: `https://flint.network`
- URL: `https://flint.network/api/x401/verify`
- Auth: one of:
  - none
  - API key in header `PROOF-RESPONSE`

Without PROOF-RESPONSE, returns a signed OpenID4VP proof challenge. With a valid presentation, verifies the principal, issues a signed verification record, and returns proof-result metadata.

## Headers

- `PROOF-RESPONSE` string

## Request body

- VerifyRequest
  - `nonce` string, required: Unique replay-protection nonce. UUID v4 is recommended.
  - `timestamp` string, date-time, required: Request timestamp. Must be within the server replay-protection window.
  - `partner_id` string: Merchant or platform identifier used for partner-scoped public IDs.
  - `merchant_reference` string: Merchant transaction, invoice, or API access reference.
  - `transaction` TransactionIntent, required
    - `amount_display` string, required: Human-readable transaction amount.
    - `amount_atomic` string, nullable: Atomic token amount when available.
    - `asset` string: Asset symbol, such as USDC.
    - `chain` string: CAIP-2 chain identifier.
    - `counterparty_address` string, nullable: Wallet or counterparty address.
    - `merchant_reference` string, nullable: Merchant reference for the intended action.
    - `tx_intent_hash` string, nullable: Optional hash of the transaction intent.
  - `declared_scope` AuthorizationScope
    - `max_amount_per_tx_display` string: Maximum amount authorized per transaction.
    - `allowed_counterparties` string[]: Allowed merchant references or counterparties.
    - `time_window_end` string, date-time: Expiration time for the declared scope.
  - `agent_claim` AgentClaim
    - `agent_id` string: Agent-provided stable identifier or handle.
    - `principal_hint` string: Principal or authority hint supplied by the agent.
    - `agent_runtime_hint` string: Agent runtime category, such as browser, api_client, or api_meter.
    - `wallet_type` string: Wallet or account type claimed by the agent.

## Response `200`

Principal presentation verified and signed record issued.

- X401VerifyResponse
  - `ok` unknown, required
  - `protocol` 'x401', required
  - `route` '/api/x401/verify', required
  - `verdict` 'allow' | 'step_up' | 'review' | 'block', required
  - `score` number, required
  - `confidence` number
  - `top_reasons` string[]
  - `record_id` string, required
  - `signed_record` string, required
  - `record` HybridEnvelope, required
    - `envelope_version` string, nullable
    - `jws` string, required: ES256 compact JWS.
    - `pq_signature` string, nullable: Parallel ML-DSA-65 signature when configured.
    - `pq_kid` string, nullable
    - `pq_alg` string, nullable
  - `x401` object, required
    - `request_id` 'flint-principal-identity-v1', required
    - `principal_attestation_source` 'x401', required
    - `principal` object, required

## Other responses

- `400`: Invalid request or presentation.
- `401`: Proof challenge required.
- `409`: The x401 verifier nonce was already used.
- `500`: Server error

---

[API](https://skmtc.dev/flint/apis/flint-agent-transaction-control-api.md) · [All operations](https://skmtc.dev/flint/apis/flint-agent-transaction-control-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flint/apis/flint-agent-transaction-control-api/revisions/eb5052b7b5dc?raw)