Health & Ops

This page covers the endpoints and operational behavior you need to run the service in production: liveness/version probes, automatic database migrations, persisted data, rate limiting, and logging.

Liveness & Version Probes

The service exposes two public, unauthenticated endpoints suitable for uptime checks and deployment verification.

GET /

Returns a plain string (Hello World!). Use it as a lightweight liveness probe.

curl https://wallet.example.com/

GET /version

Returns the service name and the running build version. Use it to confirm which release is deployed.

curl https://wallet.example.com/version

Response Body:

{ "name": "ssi-core", "version": "<build version>" }

The version value is read from the build's package.json, so it reflects whatever release is deployed.

To confirm database connectivity, call an admin-authenticated read such as GET /agent/dids (an /agent/* route requiring an admin Bearer token): a 200 indicates the service and its database are reachable. The service has no dedicated readiness endpoint.

Migrations & Persistence

Database migrations run automatically at startup against the PostgreSQL instance referenced by DATABASE_URL. Migrations are applied before the service begins serving traffic, so deployment needs no separate migration step. Point a fresh service at an empty database and it creates its own tables on first boot.

Persisted data includes:

• Hosted did:web documents served by the service over HTTPS

• Signing keys managed by the service's key store

• Credential schemas and their versions

• Authenticated users and their holder (cloud-wallet tenant) mappings

• Issued and stored credentials, plus issuance and verification session records

All persisted state is local to the service: did:web documents are created and served by the service itself, and did:key documents are self-contained (they resolve from the key material alone) — neither has any on-chain record.

Rate Limiting

A global rate limit applies to the API: 60 requests per 60 seconds per client. Requests beyond the limit receive 429 Too Many Requests. Account for this when scripting bulk issuance or running automated tests.

Public DID document serving is exempt from the rate limit, so wallets and verifiers resolving did:web documents are never throttled:

• GET /:uuid/did.json

• GET /:uuid/.well-known/did.json

Observability

• Application logs cover the issuance and verification request lifecycle (offer creation, session state changes, signing, and presentation handling), plus migration progress at startup.

• Errors are returned in a consistent envelope so failures are easy to correlate with logs:

{
  "statusCode": 404,
  "message": "DID Document not found",
  "path": "/abc123/.well-known/did.json",
  "timestamp": "2026-06-22T10:15:30.000Z"
}

For interactive inspection of the full API, the service serves Swagger UI at GET /api-docs and the raw OpenAPI document at GET /api-docs-json.