API & gRPC Reference

All REST traffic flows API Gateway → Core Engine (orchestration) → microservices (gRPC), except Admin Console, which the gateway routes to directly. Business-logic REST controllers live almost entirely in Core Engine (60+ controller classes); Admin Console owns a separate /api/v1/admin/** namespace of its own.

REST endpoints by actor

Grouped by base path — not an exhaustive per-endpoint listing. Read the named controller for a group’s full method list.

Core Engine and Admin Console both expose routes under /api/v1/admin/**, but they’re different controllers in different services, disambiguated only by sub-path — there is no shared AdminController. Check the table above before assuming which service owns a given path.

gRPC services

Proto files live in backends/shared/src/main/proto/ — 8 contracts, not the 3–4 historically documented.

Service ports

There is no BatchIssue RPC anywhere in the proto contracts — batch issuance is a REST-layer concern (POST /api/v1/credentials/batch), not a streaming gRPC method.

Authentication

1. JWT bearer tokens — API Gateway validates for issuers, holders, verifiers, custodians.
2. Service-to-service mTLS — every internal gRPC connection requires mutual TLS with no plaintext fallback; a missing/invalid certificate fails the connection outright. See Internal gRPC mTLS.
3. API keys — for custodial-issuer headless integrations. An issuer generates a server-to-server key via POST /api/v1/issuer/{issuer_did}/api-keys, then presents it as X-Api-Key on /api/v1/credentials/issue and /api/v1/credentials/batch instead of a JWT. See Issuer API Keys.

See API Gateway for gateway-level auth config.

Error handling

REST — standard HTTP status codes with a JSON error object:

{
  "error": "CREDENTIAL_EXPIRED",
  "message": "The provided credential has expired and is no longer valid.",
  "timestamp": "2026-03-15T10:30:00Z",
  "correlationId": "uuid-for-tracking"
}

gRPC — standard Status codes:

Rate limiting

Redis-backed, per-route (not one blanket tier), via RateLimitingGatewayFilterFactory, keyed per authenticated user/issuer or else per IP. Representative ceilings from GatewayConfig.java:

GatewayConfig is the authoritative, current per-route list — it changes independently of this page.

Versioning

• v1 — current stable API, in active use by every route above.
• v2 — not yet started; no v2 routes or deprecation plan exist in the codebase.