Service Contracts

This document defines the contracts and standards for inter-service communication.

Standard Headers

Required on ALL Requests

Authorization: Bearer <access_token>
X-Correlation-Id: <uuid>
Content-Type: application/json
Accept: application/json

After Authentication (Set by Backend)

X-Tenant-Id: <tenant_id>        # From JWT claims
X-User-Id: <user_id>            # From JWT claims
X-Request-Id: <uuid>            # Generated per request

M2M (Service-to-Service)

Authorization: Bearer <service_principal_token>
X-Service-Principal: <service_name>
X-Correlation-Id: <uuid>

ID Standards

ID Type	Format	Example
tenant_id	UUID v4	550e8400-e29b-41d4-a716-446655440000
user_id	UUID v4	7c9e6679-7425-40de-944b-e07fc1f90ae7
customer_id	Integer/UUID	12345
contract_id	contract_ + UUID	contract_a1b2c3d4-5678-90ab
license_key	QCOS-XXXX-XXXX-...	QCOS-41FB-639F-C30B-14E3
bundle_id	bundle_ + timestamp + UUID	bundle_20250104_abc123

Error Response Format

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found",
    "details": {
      "resource_type": "license",
      "resource_id": "QCOS-XXXX-XXXX"
    },
    "correlation_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "timestamp": "2025-01-04T10:00:00Z"
  }
}

Error Codes

HTTP	Code	Description
400	INVALID_REQUEST	Malformed request
400	VALIDATION_ERROR	Field validation failed
401	UNAUTHORIZED	Missing/invalid token
401	TOKEN_EXPIRED	JWT expired
403	FORBIDDEN	Insufficient permissions
403	TENANT_MISMATCH	Cross-tenant access
404	RESOURCE_NOT_FOUND	Resource doesn't exist
409	CONFLICT	State conflict
429	RATE_LIMITED	Too many requests
500	INTERNAL_ERROR	Server error
503	SERVICE_UNAVAILABLE	Dependency down

Service Endpoints

QSA (Identity Provider)

Endpoint	Method	Description
/.well-known/openid-configuration	GET	OIDC discovery
/.well-known/jwks.json	GET	JSON Web Key Set
/oauth2/authorize	GET	Authorization
/oauth2/token	POST	Token exchange
/oauth2/revoke	POST	Token revocation
/api/v1/users	CRUD	User management
/api/v1/mfa/*	POST	MFA operations

QuantumLock

Endpoint	Method	Description
/api/v1/licenses/generate	POST	Generate license
/api/v1/licenses/validate	POST	Validate license
/api/v1/licenses/{key}	GET	Get license details
/api/v1/licenses/{key}/revoke	POST	Revoke license
/api/v1/revocations	GET	List revocations
/api/v1/quantum/crypto/sign	POST	Sign message
/api/v1/quantum/crypto/verify	POST	Verify signature

Portal Backend

Endpoint	Method	Description
/api/customers	CRUD	Customer management
/api/contracts	CRUD	Contract management
/api/entitlements	CRUD	Entitlements
/api/v2/jobs/{id}/evidence	GET	Get evidence
/api/v2/jobs/{id}/artifacts	GET	List artifacts
/api/v2/evidence/verify	POST	Verify evidence

Rate Limits

Service	Limit	Window
QSA Token	100/min	Per client
QSA API	1000/min	Per tenant
QuantumLock Generate	Per plan	Monthly
QuantumLock Validate	10000/min	Per client
Portal API	1000/min	Per user
Evidence API	500/min	Per tenant

Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1704369600

Health Checks

All services expose:

GET /health   # Liveness
GET /ready    # Readiness

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-01-04T10:00:00Z",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "storage": "ok"
  }
}

Observability

Logging Format

{
  "timestamp": "2025-01-04T10:00:00.123Z",
  "level": "INFO",
  "service": "portal-backend",
  "correlation_id": "9b1deb4d-...",
  "tenant_id": "550e8400-...",
  "user_id": "7c9e6679-...",
  "message": "License generated",
  "data": {
    "license_key": "QCOS-XXXX-****"
  }
}

Metrics (Prometheus)

http_requests_total{service, method, endpoint, status}
http_request_duration_seconds{service, method, endpoint}
licenses_generated_total{plan, tenant}
evidence_bundles_created_total{tenant}

Tracing

All services propagate OpenTelemetry context:

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
tracestate: softquantus=tenant:abc123

Versioning

• All APIs use path versioning (/api/v1/, /api/v2/)
• Breaking changes require major version bump
• 6-month deprecation notice for major changes
• Parallel support for N and N-1 versions

Deprecation Headers:

Sunset: Sat, 04 Jul 2026 00:00:00 GMT
Deprecation: true
Link: <https://docs.softquantus.com/migration>; rel="deprecation"