Hyfa API Overview

The Hyfa API exposes identity, attestation, discovery, and payment operations for the Hyfa protocol. All endpoints are served from a single base URL.

Base URL

All API requests are made to:

https://api.hyfa.id

Authentication

Hyfa uses a two-tier authentication model. Public read endpoints require no credentials. Dashboard and write endpoints require an API key issued to your organization when you register a did:hyfa identity.

Pass your API key in the Authorization header:

Authorization: Bearer hyfa_key_<your_api_key>

Versioning

All endpoints are prefixed with /api/v1. The current version is v1. Breaking changes will increment the version prefix.

Response format

All responses are JSON. Successful responses return HTTP 200 with a JSON body. Errors return an appropriate 4xx or 5xx status with a structured error object:

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "No agent registered with the provided DID.",
    "request_id": "req_01hx..."
  }
}

Rate limits

Public endpoints: 60 requests / minute per IP. Authenticated endpoints: 300 requests / minute per API key. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers.

Worked example — GET /api/v1/status

The status endpoint is a good first call to verify connectivity and check the active network. It requires no authentication.

This endpoint also serves as the reference template for all endpoint entries in B.2 / B.3 / B.4 — every section that follows this pattern (header, description, auth note, request, response, errors).

curl https://api.hyfa.id/api/v1/status

{
  "status": "ok",
  "version": "1.0.0",
  "network": "testnet",
  "timestamp": "2026-03-24T12:00:00Z"
}

Template guide for B.2 / B.3 / B.4

The endpoint block above is the standard format for every endpoint entry across the API reference sections. Copy the HTML structure from the .endpoint div and fill in:

• Method badge — use class method-get, method-post, method-put, or method-del
• Path — full path including /api/v1/ prefix
• Auth note — use .doc-note block; state public vs. API key required
• Request body table — .params-table; mark required fields with .required-badge
• curl example — real, copy-pasteable example using testnet values
• Success response — actual JSON shape with field descriptions
• Error table — all meaningful 4xx/5xx codes the endpoint can return

API sections