API Reference

REST and WebSocket interfaces for verification requests and record queries.

Authentication

API requests require authentication via API key in the Authorization header. Keys are scoped to permitted verification operations and rate-limited by subscription tier.

Authorization Header

Authorization: Bearer fhp_live_xxxxxxxxxxxxx

Endpoints

POST/v1/attestations

Create a new verification request

Request Body

{
  "type": "identity" | "age" | "jurisdiction" | "accreditation",
  "subject": "SUBJ-2048-A",
  "parameters": { ... },
  "callbackUrl": "https://..."
}

GET/v1/attestations/:id

Retrieve verification status and record

Response

{
  "id": "att_xxxxxxxx",
  "status": "pending" | "verified" | "rejected",
  "proof": "hex_proof_payload",
  "commitment": "hex_commitment",
  "expiresAt": "2027-02-26T00:00:00Z"
}

POST/v1/verify

Verify a submitted proof payload

Request Body

{
  "proof": "hex_proof_payload",
  "publicInputs": ["input_a", "input_b"],
  "attestationType": "identity"
}

GET/v1/subjects/:address/attestations

List verification records for a subject identifier

Query Parameters

type: Filter by attestation type
status: Filter by verification status
limit: Maximum records (default: 20)

WebSocket API

Real-time verification status updates are available via WebSocket. Connect to receive notifications for record state changes.

Connection URL

wss://api.fhprotocol.io/v1/ws

Subscribe Message

{
  "action": "subscribe",
  "channel": "attestations",
  "subject": "SUBJ-2048-A"
}

Rate Limits

Tier

Requests/min

Attestations/day

Developer

100

Production

600

10,000

Enterprise

Unlimited