Skip to main content

Architecture Surfaces

Use this page to understand how Zerq is structured before you configure anything.

What this page covers​

  • Simple mental model of platform surfaces
  • Where requests flow at runtime
  • What each surface is responsible for

Platform surfaces​

1) Management surface​

Where teams define and publish platform configuration:

  • Collections and proxies
  • Clients, profiles, and policies
  • Workflow configuration
  • Credential configuration

2) Gateway runtime surface​

Where live API traffic is authenticated, authorized, processed, and forwarded.

3) Developer portal surface​

Where API consumers discover endpoints, run tests, and export cURL/OpenAPI.

4) MCP surface​

Where AI clients and agent automation connect through Gateway MCP and Management MCP.

5) Observability surface​

Where teams inspect request logs, audit trails, and metrics.

End-to-end request path​

  1. Caller sends request with Authorization, X-Client-ID, and X-Profile-ID for profile-authenticated gateway flows.
  2. Gateway resolves route to a published collection/proxy.
  3. Policy and auth checks run before workflow execution.
  4. Request is forwarded or processed, then response is returned and logged.

Common status outcomes​

  • 401: authentication did not pass.
  • 403: authenticated identity is outside allowed policy scope.
  • 405: route does not support that HTTP method.
  • 429: request exceeds configured limit.

Quick verification​

curl -i "https://gateway.example.com/healthz"