OpenAPI and HTTP integration

What the HTTP binding provides

The OpenAPI document exposes the implemented vertical slice and typed contract components. It is an experimental binding of CALI semantics, not the specification itself. A future gRPC binding should preserve the same policy, failure and evidence behavior.

Endpoint map

Endpoint	Purpose
GET /healthz	process health only; no crypto readiness claim
GET /v2/capabilities	scoped, freshness-bounded deployment capabilities
POST /v2/policies:resolve	privileged policy-resolution diagnostic
POST /v2/keys	create an opaque key reference under pinned policy
GET /v2/keys/{keyRef}	retrieve public metadata and lifecycle state
POST /v2/sign	sign with an authorized opaque key reference
POST /v2/verify	verify under the selected profile

Authentication and tenant context

The development server can require a bearer token and accepts an X-CALI-Tenant header. These are harness controls, not a production identity design. Production deployments must bind authenticated workload identity to tenant, policy subject, authorization and audit context.

Create and sign

curl -sS -X POST http://127.0.0.1:8080/v2/keys \
  -H 'Content-Type: application/json' \
  -H 'X-CALI-Tenant: example-tenant' \
  --data @implementation/examples/create-key.example.json

The response returns an opaque keyRef, public metadata, policy version, provider class and evidence. It never returns private key material.

Error handling

Clients should branch on the stable CALI error category, not parse provider messages. Provider detail may be included only when authorized and safe. Retrying POLICY_AMBIGUOUS, CAPABILITY_MISMATCH or IDEMPOTENCY_CONFLICT without changing state is not useful.

Generating a client

An engineer may use any OpenAPI 3.1-capable generator, but generated transport types do not replace policy-aware application handling. Pin the document version, review base64url encoding rules, preserve unknown error detail safely and test request rejection as carefully as success.

npx @openapitools/openapi-generator-cli generate \
  -i implementation/api/openapi/cali-v2.openapi.json \
  -g typescript-fetch \
  -o generated/cali-client

Browser and cross-origin use

The reference service is intended for local or service-to-service study. Do not expose it directly to untrusted browsers without an explicit CORS, authentication, rate-limit, request-size and evidence-access design.