API Surface

Issue and verify with explicit trust boundaries

Authenticated write endpoints live under /api/*. Public verification endpoints live under /public/api/*, enforce SSRF protections, and include rate-limited trust-log bootstrap.

Run live verify test Open verifier

Issue and verify quickstart

Use this exact sequence to test end-to-end behavior in minutes.

1. Validate issuer domain

GET /api/validate-issuer-domain

2. Create issuer and badge class

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

3. Issue credential

POST /api/credential-subject

4. Verify publicly

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

Authentication

Authenticated requests require X-API-Key

Attach the key to admin and issuance requests. Public verification and public issuer trust bootstrap are keyless.

Header 
X-API-Key: <API_KEY>
Public verify call 
curl "https://badges.firmament.works/public/api/verify/badge/https%3A%2F%2Fexample.com%2Fbadges%2Fassertion.json"
Create issuer 
curl -X POST "https://badges.firmament.works/api/issuer" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <API_KEY>" \
  -d '{
    "id":"https://demo.example.org/issuer",
    "name":"Demo Academy",
    "url":"https://demo.example.org",
    "email":"[email protected]"
  }'

Endpoint map

Grouped by job to be done

Public verification plane
  • GET /public/api/verify/badge/:badgeUrl(*) Fetch and verify a remote badge URL.
  • GET /public/api/verify/issuer/:issuerUrl(*) Verify an issuer profile URL.
  • POST /public/api/verify/json Verify inline badge JSON object.
  • POST /public/api/issuers/verify Verify domain well-known profile and add issuer to trust log (rate-limited).
Issuance plane
  • GET /api/validate-issuer-domain Validate domain usage constraints.
  • POST /api/issuer Create a hosted issuer JSON resource.
  • POST /api/badge-class Create a hosted badge class JSON resource.
  • POST /api/credential-subject Issue a hosted assertion JSON resource.
Issuer operations
  • POST /api/issuers/verify Verify domain ownership via well-known profile.
  • GET /api/issuers List verified issuer records.
  • POST /api/issuers/:domain/reverify Re-run issuer verification.
Proof and key operations
  • POST /api/sign-badge Add a proof block to badge payload.
  • POST /api/cache-public-key Cache issuer public keys by domain.
  • GET /api/badge-files List hosted JSON resources.
Full documentation

Implementation-specific additions

Public safety

SSRF protections by default

Public verification routes validate protocols and block internal/private address ranges.

Issuer trust

Domain verification workflow

Issuer verification and re-verification endpoints enforce well-known profile ownership checks.

Automation

Agent-ready operations

CLI, MCP, and llms.txt support machine-readable issuance and verification workflows.