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#

Server Configuration#

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