API Reference

Public verification.
Authenticated issuance.

No-key routes under /public/api/* handle verification and trust discovery. Authenticated routes under /api/* manage issuance and signing.

Open verifier Run challenge

Issue and verify

Minimal sequence from domain readiness to public verification.

01

Verify issuer domain

POST /public/api/issuers/verify

Check that your domain's /.well-known/openbadges-issuer.json endpoint is reachable and returns a valid issuer profile. Rate-limited — no API key required.

02

Create issuer and badge class

POST /api/issuer POST /api/badge-class

Register your issuer profile and define the badge class — the template that describes what the credential represents. Both endpoints require an API key.

03

Issue and sign

POST /api/credential-subject POST /api/sign-badge

Create a credential subject record for the earner, then sign the badge with your Ed25519 private key. The result is a self-contained, portable JSON assertion.

04

Verify publicly

GET /public/api/verify/badge/:badgeUrl(*)

Anyone can verify a badge by URL. The public verifier fetches the JSON, validates structure and signature, and checks issuer key discoverability — returning a clear trust state with no authentication required.

Public — no key required

Verify and discover trust

All verification and trust-discovery operations run without authentication.

Verify a signed sample 
curl "https://badges.firmament.works/public/api/verify/badge/https%3A%2F%2Fbadges.firmament.works%2Fsamples%2Fdemo-openbadge-v3-signed.json"
Expected response fields 
{
  "trustState": "DEMO_DOMAIN_VERIFIED_SIGNATURE",
  "issuerDomain": "example.com",
  "validationLabel": "DEMO",
  "keyFingerprint": "sha256:...",
  "verificationReason": "Signature is valid. Issuer uses the reserved example.com demo domain.",
  "issuerClaimedName": "EXAMPLE.com Demo Issuer"
}
Trust discovery 
curl "https://badges.firmament.works/public/api/trust/issuer/badges.firmament.works"
curl "https://badges.firmament.works/public/api/trust/events/badges.firmament.works"
curl "https://badges.firmament.works/public/api/trust/issuers?status=verified"
Trust write (rate-limited, no key) 
curl -X POST "https://badges.firmament.works/public/api/issuers/verify" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.org"}'

Authenticated — X-API-Key required

Issuance and signing

Issuance, signing, and admin operations require a valid API key in the request header.

Auth header 
X-API-Key: <API_KEY>
Authenticated endpoint map 
GET  /api/validate-issuer-domain
POST /api/issuer
POST /api/badge-class
POST /api/credential-subject
POST /api/sign-badge
POST /api/cache-public-key
GET  /api/badge-files
GET  /api/metrics

Agent-native

Human and LLM workflows use the same contract. See llms.txt for machine-readable docs, or connect via the MCP server for tool-native operations.

Implementation-specific behavior

Distinct additions beyond baseline issuance and verification.

Security

SSRF-hardened verifier routes

Public verify endpoints block localhost and private-network fetch targets before any server-side retrieval occurs.

Trust policy

Domain ownership verification

Trust writes are tied to issuer metadata at /.well-known/openbadges-issuer.json with rate limits and cooldown controls.

Interfaces

API + CLI + MCP + llms.txt

Human and LLM workflows issue, verify, and inspect trust state through the same public contract with identical semantics.

Endpoint reference

All public routes. No authentication required.

Verification plane

  • GET /public/api/verify/badge/:badgeUrl(*)
    Fetch and verify a remote badge URL.
  • GET /public/api/verify/issuer/:issuerUrl(*)
    Validate issuer profile and key discoverability.
  • POST /public/api/verify/json
    Verify an inline badge JSON object.

Trust plane

  • POST /public/api/issuers/verify
    Rate-limited trust write by domain ownership proof.
  • GET /public/api/trust/issuer/:domain
    Read issuer trust state record.
  • GET /public/api/trust/events/:domain
    Read recent trust events for a domain.
  • GET /public/api/trust/issuers?status=verified
    List trusted issuers by status filter.