System

`GET /health`

No auth required.

200 OK — all dependencies reachable

{ "status": "ok", "liveness_mode": "stub", "dependencies": { "db": true, "cache": true, "face_engine": true, "identity_registry": true } }

503 Service Unavailable — DB or Redis down

{ "status": "degraded", "liveness_mode": "stub", "dependencies": { "db": false, "cache": true, "face_engine": true, "identity_registry": true } }

Only db/cache being down flips the overall status to degraded and the HTTP status to 503 — face_engine/identity_registry are reported but don’t fail this endpoint, since their absence degrades specific flows (linking, identify) rather than the whole service. Ops tooling should still alert on either being false.

`GET /models`

No auth required.

200 OK

{
  "model_version": "arcface-w600k_r50-v1",
  "liveness_mode": "heuristic",
  "face_engine": { "embedder_model": "arcface_w600k_r50.onnx", "detector_model": "face_detection_yunet.onnx", "model_version": "arcface-w600k_r50-v1", "embedding_dim": 512 }
}

face_engine is null if that service is unreachable — this endpoint queries its real GET /v1/version live, rather than trusting a locally hardcoded assumption about what’s deployed.

`GET /metrics`

No auth required — consistent with standard Prometheus scrape-target convention (restrict via network policy, not application auth, in a real deployment). Returns every metric in Prometheus text-exposition format: default Node.js process metrics (CPU, memory, event-loop lag), generic HTTP request/duration counters, and the business-outcome counters described in Observability.

# HELP facetrust_http_requests_total Total HTTP requests, labeled by method/route/status_code
# TYPE facetrust_http_requests_total counter
facetrust_http_requests_total{method="GET",route="/health",status_code="200",service="facetrust-api"} 1
...

facetrust_dependency_up{dependency="..."} (0/1 gauge per dependency) is updated by a background poller every 15 seconds — independent of anyone actually calling GET /health — so it stays fresh even in a deployment where nothing ever hits that endpoint directly.

`GET /settings/attestation-required`

Administrator bearer token required.

200 OK

{ "attestationRequired": true, "mutable": false }

`PATCH /settings/attestation-required`

Always rejected — there is no code path that changes this value.

403 Forbidden

{ "error": "forbidden", "message": "attestation-required is a locked compliance control and cannot be modified" }

Getting Started

Architecture

Security

API Reference

`GET /health`

`GET /models`

`GET /metrics`

`GET /settings/attestation-required`

`PATCH /settings/attestation-required`

​GET /health

​GET /models

​GET /metrics

​GET /settings/attestation-required

​PATCH /settings/attestation-required

`GET /health`

`GET /models`

`GET /metrics`

`GET /settings/attestation-required`

`PATCH /settings/attestation-required`