API Surfaces Overview

The platform exposes three distinct API surfaces, each designed for a specific audience and purpose. Understanding which API to use is the first step in integrating with the platform. The two primary surfaces for integration are the Admin API and the Runtime API.

How it Works

Authentication Models

The platform uses different authentication and authorization mechanisms for its control-plane and data-plane APIs.

Admin API Authentication

The Admin API is designed for internal management and is not publicly accessible. In a standard deployment, it is protected by an identity-aware ingress, such as Google IAP or another OIDC/SAML front door.

The platform determines the caller's identity by inspecting forwarded headers from the ingress.

sequenceDiagram
    participant C as API Caller
    participant IAP as Identity-Aware Proxy
    participant P as Platform (Admin API)

    C->>IAP: Call GET /admin/v1/services
    IAP->>P: Forward request with identity headers
    Note over P: Resolves caller identity and role<br/>from forwarded headers.
    P-->>IAP: 200 OK or 403 Forbidden
    IAP-->>C: 200 OK or 403 Forbidden

Identity Headers:

The resolved identity is mapped to one of three application roles: admin, operator, or reader. This mapping occurs through role bindings configured via IdP group membership, direct in-app assignments, or a bootstrap list. An attempt to perform an action not permitted for the caller's role will result in a S2R-ADM-0403 error.

You can verify your resolved identity and role by calling the GET /admin/v1/me endpoint.

Runtime API Authentication

The Runtime API is the live traffic path. Authentication for inbound calls from API consumers is handled by the API publisher's own ingress or API gateway, which sits in front of the platform's runtime component. The runtime itself is not directly exposed.

The runtime's own credential management is focused on authenticating its outbound calls to backend services.

Request Routing

The base path of a request URL determines which API surface handles it.

• Admin API: All endpoints are prefixed with /admin/v1. Path references in the documentation, such as /services, are relative to this base (e.g., GET /admin/v1/services).
• Runtime API: All conversion routes must begin with a direction segment: /publish/{env}/{serviceKey}/{op...} or /consume/{env}/{serviceKey}/{op...}. A request that omits the direction segment is rejected with the error code S2R-RUN-0405.

Correlation IDs

Every request processed by the Runtime API is tagged with a correlation ID, which is essential for end-to-end observability. This ID links the inbound call, the backend call, all internal processing steps, structured logs, and debug traces.

• To supply a custom correlation ID, send it in the X-Correlation-Id request header.
• If the X-Correlation-Id header is absent, the runtime generates a new unique ID for the request.
• The correlation ID is echoed in the X-Correlation-Id response header.
• It is also included in the standard error envelope, allowing a failed request to be traced from the error received by the consumer back through the system's logs and traces.

Standard Error Envelope

Both the Admin and Runtime APIs return errors in a consistent JSON format to provide predictable, machine-readable error details.

{
  "error": {
    "code": "S2R-RUN-0413",
    "message": "Payload too large",
    "details": {
      "maxPayloadMb": 30
    },
    "correlationId": "00000000-0000-0000-0000-000000000000"
  }
}

Error Fields

API Endpoint Reference

GET /admin/v1/me

Returns the resolved identity and application role for the caller making the request to the Admin API. This is useful for confirming the identity being used by the platform after authentication by the ingress proxy. The UI uses this endpoint to tailor the user experience based on the caller's role.

Troubleshooting

• Tracing Failures: When a request fails, use the correlationId from the error envelope to find all associated logs, traces, and metrics across the observability platform. If you are providing your own ID via the X-Correlation-Id header, ensure it is unique per request.
• Admin API Access Denied: If you receive a 403 Forbidden response with error code S2R-ADM-0403, it means your resolved identity does not have the required role (admin, operator, or reader) to perform the requested action. Check your role with GET /admin/v1/me and consult your platform operator about role bindings.
• Runtime API Routing Error: If you receive error code S2R-RUN-0405, check that your request URL includes the required direction segment (/publish/ or /consume/) immediately after the base path.

See Also

• Admin (control-plane) API
• Runtime API
• Error codes
• RBAC & roles
• Observability overview

All SOAP-to-REST docs