Relay Heartbeat API

Overview

The Relay Heartbeat API provides a gateway endpoint for receiving periodic self-reports from relay agents. Relay agents are components that run within an API consumer's network and require a mechanism to report their status and version back to the central platform.

This endpoint, POST /relay/v1/heartbeat, solves the problem of monitoring re<customer>e relay agents by providing a secure and authenticated channel for them to send liveness signals. Upon receiving a valid heartbeat, the platform updates its record of the relay's last-seen time and current software version.

The endpoint is called exclusively by relay agents. It authenticates the agent using a dedicated relay key, validates the request, and persists the liveness information. It is a SaaS-only feature and is only available on platform instances with a license that grants the SaaS capability.

How it Works

When a relay agent sends a request to the /relay/v1/heartbeat endpoint, the gateway performs a series of validation and authentication steps before processing the heartbeat.

flowchart TD
    subgraph "Relay Agent"
        A[POST /relay/v1/heartbeat]
    end

    subgraph "API Gateway"
        B{SaaS Licensed?}
        C{Header X-S2R-Relay-Key Present?}
        D[Hash Key]
        E{Key Hash Found?}
        F{Credential Active?}
        G{Body relayId matches Key's relayId?}
        H[Record Heartbeat in DB]
        I[Return 204 No Content]
        J[Return 404 Not Found]
        K[Return 401 Unauthorized]
        L[Return 403 Forbidden]
    end

    A --> B
    B -- No --> J
    B -- Yes --> C
    C -- No --> K
    C -- Yes --> D
    D --> E
    E -- No --> K
    E -- Yes --> F
    F -- No --> L
    F -- Yes --> G
    G -- No --> L
    G -- Yes --> H
    H --> I

The processing flow is as follows:

1. License Check: The system first verifies that the active license grants the SaaS capability. If not, the endpoint returns an HTTP 404 Not Found response, making it invisible on non-SaaS deployments. This check is performed on every request.

2. Header Validation: The endpoint requires the X-S2R-Relay-Key header. If the header is missing or its value is blank, the request is rejected with an HTTP 401 Unauthorized (S2R-RUN-0460).

3. Key Authentication: The provided relay key is hashed using SHA-256. The system looks up this hash in the database. If no matching key is found, the request is rejected with an HTTP 401 Unauthorized (S2R-RUN-0460). This response is intentionally identical to that for a missing key to prevent credential enumeration attacks.

4. Credential Status: If the key is found, the system checks if the credential is active. If it has been revoked, the request is rejected with an HTTP 403 Forbidden (S2R-RUN-0461).

5. Relay ID Matching: The relayId provided in the JSON request body must match the relayId associated with the authenticated key. A key is bound to a specific relay and cannot be used to report heartbeats for a different one. A mismatch results in an HTTP 403 Forbidden (S2R-RUN-0462).

6. Record Heartbeat: On successful authentication and validation, the system binds the request context to the relay's parent tenant. It then updates the database, recording the relay's version from the request and setting its last_heartbeat_at timestamp to the current server time.

   IMPORTANT

   The gateway's clock is authoritative for the liveness timestamp. The reportedAt field from the agent's request is accepted in the payload but is not used to set the last_heartbeat_at value. This prevents an agent from back-dating or future-dating its liveness signal.

7. Response: The endpoint returns an HTTP 204 No Content response to indicate success.

API Reference

POST /relay/v1/heartbeat

Receives a heartbeat from a relay agent, authenticates it, and records its liveness and version.

Request Headers

Request Body

The request body must be a JSON object with the following fields.

Example Request

curl -X POST \
  'https://<GATEWAY_HOST>/relay/v1/heartbeat' \
  -H 'Content-Type: application/json' \
  -H 'X-S2R-Relay-Key: <RELAY_KEY>' \
  -d '{
    "relayId": "relay-a1b2c3d4",
    "version": "v1.2.3",
    "status": "running",
    "reportedAt": "2023-10-27T10:00:00Z"
  }'

Responses

• 204 No Content: The heartbeat was successfully received and processed.
• 401 Unauthorized: Authentication failed. The response body contains an error code.
• 403 Forbidden: Authorization failed. The response body contains an error code.
• 404 Not Found: The SaaS capability required for this endpoint is not enabled in the platform's license.

Troubleshooting

When a heartbeat request fails, the API returns an HTTP error status and a JSON body containing an error code.

In rare cases where the database update fails after a successful authentication, a warning (S2R-RELAY-HEARTBEAT no-op) is logged on the server. However, the API will still return a 204 No Content to the client to prevent the relay agent from entering a failed state due to a transient server-side issue.

See Also

• SaaS multi-tenant architecture concepts
• Relay agent image and version reconciliation details

All SOAP-to-REST docs