API Surface Design#

Detailed API surface for the scafctl REST API server. All endpoints use JSON request/response bodies and follow REST conventions.

Base URL#

http://localhost:8080

Version-prefixed endpoints use /{apiVersion}/ (default: /v1/).

Authentication#

• Method: Entra OIDC (Azure AD) JWT Bearer tokens
• Header: Authorization: Bearer <token>
• Public endpoints: Health probes and metrics bypass authentication
• Admin endpoints: Require authentication + admin role claim (or localhost-only when auth is disabled)

Response Format#

Success (single resource)#

{
  "fieldA": "value",
  "fieldB": 42
}

Success (collection with pagination)#

{
  "items": [...],
  "pagination": {
    "page": 1,
    "per_page": 100,
    "total_items": 250,
    "total_pages": 3,
    "has_more": true
  }
}

Error (RFC 7807 Problem Details)#

{
  "title": "Bad Request",
  "status": 400,
  "detail": "validation failed: name is required"
}

Naming Conventions#

Endpoints#

Operational (Root Router — No Auth)#

Solutions#

Providers#

Eval#

Catalogs#

Schemas#

Config#

Snapshots#

Explain & Diff#

Admin#

Documentation (Auto-Generated by Huma)#

Common Query Parameters#

Global Status Codes#

These status codes can be returned by any endpoint, in addition to endpoint-specific codes:

Middleware Stack#

The API uses a two-layer middleware architecture. Health probes and metrics bypass the API middleware entirely.

Global Middleware (All Routes)#

API Middleware (Business Endpoints)#

Rate Limiting#

When rate limiting is enabled, every API response includes standard rate limit headers:

Security#

Security Headers#

All API responses include the following security headers:

TLS Support#

The server supports TLS with configurable certificate and key paths. When TLS is enabled, HSTS headers are automatically added to all responses.

CEL Filter Sandboxing#

User-supplied filter expressions are evaluated with:

• Cost limit: 10,000 (lower than CLI default of 1,000,000)
• Read-only: No I/O, no mutations, no filesystem access
• Max length: 2,000 characters

Audit Log Redaction#

Request bodies in audit logs have sensitive fields redacted:

• Fields matching password, secret, token, key, credential, authorization → [REDACTED]

Admin Authorization#

The loopback check reads only the peer address (RemoteAddr). Proxy headers (X-Forwarded-For, Forwarded, X-Real-IP) are never trusted to grant access – a remote caller cannot claim to be localhost by setting them.

Reverse-proxy caveat: when the server is fronted by a proxy on the same host, every forwarded request arrives with RemoteAddr = 127.0.0.1, which would otherwise satisfy the loopback check for internet callers. To close that, a loopback request carrying any proxy-hop header is denied rather than allowed, since those headers prove a hop occurred. Operators fronting the server with a proxy should additionally block /v1/admin/ at the proxy and enable authentication.

Server Configuration#

The API server is configured via the apiServer section in the scafctl config file:

Where these bounds are enforced#

The maximum / maxItems struct tags on APIServerConfig describe the bounds to schema consumers, but the config loader does not apply struct tags. The values above are therefore checked by APIServerConfig.Validate, which runs on every path that can start a server:

• config.Manager.Load – the file/env/flag configuration path used by scafctl serve.
• api.NewServer – the embedder path. NewServer(WithServerConfig(cfg)) accepts a hand-built config that never went through the loader, so it validates before constructing anything and returns an error on a violation.
• api.SetupMiddleware – exported separately, takes its own *config.APIServerConfig, and is the only consumer of allowedHosts.

Embedder note: NewServer and SetupMiddleware return an error for an apiServer config that exceeds a documented bound. A limit that only the file-loading path honours is not a limit, so this is deliberate – but an embedder that was previously passing an out-of-bounds value will now fail at construction instead of silently running unbounded.