Skip to main content

API Gateway

Every published API runs behind Hrida.ai's built-in API gateway. Publishing registers the API's Tool Server entry against the gateway, never against the raw upstream_base_url, whether or not the API has mappers. Agents call the gateway; the gateway applies your policy, adds the upstream credential and forwards the call.

POST/GET/PUT/PATCH/DELETE  /api/v1/api-definitions/{id}/proxy/{path}

Routing everything through one place means rate limits, size caps, caller identity, auditing, masking and the network checks apply to every API. The real upstream credential also never appears in the Tool Server configuration — only the gateway holds it.

Request pipeline​

Each call passes these stages in order. A call refused at any stage never reaches the upstream.

#StageRefused with
1Path check — . and .. segments are rejected400 invalid_path
2Published check — only a currently published API is reachable404 not_found
3Gateway secret — the per-API bearer secret registered on the Tool Server401 unauthorized
4Caller identity — the signed X-Hrida-Caller token, verified when present and required when the API's policy says so401 caller_identity_required / caller_token_invalid / caller_token_expired
5Access re-check — the caller must still have access to the API's Tool Server403 caller_forbidden
6Rate limits — per API and per user429 rate_limited + Retry-After
7Request size cap413 request_too_large
8Schema validation (opt-in) — parameters and JSON body against the OpenAPI spec400 request_invalid
9Request mappers — message reshape, then protocol encode502 request_mapping_failed / request_encoding_failed
10Upstream checks — host allow-list and DNS check against internal addresses502 upstream_blocked
11Upstream call — with upstream auth and TLS applied, a streamed and capped response read, and retries502 upstream_unreachable / upstream_response_too_large, 504 upstream_timeout
12Response mappers — protocol decode, then message reshape502 response_decoding_failed / response_mapping_failed
13Masking (opt-in) — sensitive values in the response are masked—

Every call, allowed or refused, writes one row to the Gateway Call Log. The limits and opt-in checks in stages 4–8 and 13 are set per API under Gateway Policy & Security.

Stage 1 matches the request against the API's OpenAPI spec to find the operationId, resolving path templates such as /pets/{petId}. When a literal path and a templated path both match, the more specific literal path wins. Only operations in the spec are reachable; anything else returns 404 no_matching_operation.

Error responses​

Refusals and failures return a short JSON body with no internal details:

{
  "error": "rate_limited",
  "message": "Rate limit exceeded for this API (600 calls per minute). Retry shortly.",
  "reference": "8c4c7952936e"
}

The error code identifies the stage (see the table above). The reference matches a server log line that holds the full detail — upstream host names, exception text, mapper errors — so support can find exactly what happened without that detail ever reaching the calling agent or the model's context.

Upstream responses themselves (including upstream 4xx/5xx) are passed through with the upstream's status code.

Authentication into the gateway​

The gateway holds your real, decrypted upstream credential, so it needs its own lock:

  • Each API has a random gateway secret, created on first publish. The Tool Server entry carries it as a bearer key; every call must present Authorization: Bearer <gateway secret>.
  • The check fails closed: no secret, no access.
  • The secret can be rotated at any time — see Secret rotation.

Caller identity​

The gateway secret proves a call came from Hrida.ai; the caller token says who it's for. When an agent calls a published API, Hrida.ai attaches a short-lived signed token in the X-Hrida-Caller header with the user, chat and message.

  • The token is signed with the instance secret, carries the audience hrida-api-gateway and the API's id, and expires after 15 minutes (API_GATEWAY_CALLER_TOKEN_TTL_SECONDS). A normal session token, or a token minted for a different API, is rejected.
  • When present, the gateway re-checks that user against the API's current access grants on every call — a user removed from the API Space loses access mid-conversation, not just at the next tool listing.
  • It drives the per-user rate limit and the user column of the call log.
  • Turn on Require a signed caller identity in the API's gateway policy to refuse any call that doesn't carry one.

Response handling​

  • JSON responses are mapped and masked as configured, then returned as JSON.
  • XML and other text responses without a response mapper are returned unchanged with the upstream's Content-Type (masked if masking is on).
  • Binary responses (PDFs, images, archives) are passed through byte for byte with the upstream's Content-Type.
  • Non-JSON request bodies (form posts, file uploads) without a request mapper are forwarded as-is with the caller's Content-Type.

Reliability​

  • Timeout — the same per-call budget used for every tool-server call (AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER).
  • Retry — connection failures (timeout, refused, DNS) always retry, since the request never reached the upstream. Received responses retry only for 503 (any method) or 500/502/504 on GET/HEAD, so a POST that reached the server is never re-run. Backoff doubles each attempt, up to 3 attempts.
  • Bounded memory — the upstream response is read in chunks and abandoned as soon as it passes the API's response-size cap.
Hrida.ai is proprietary software of Zlabs Innovation. See the license for terms. © 2026 Zlabs Innovation.