Gateway and security — Docs

How the APIHiver gateway protects your API: secret headers, request limits and exactly what we forward to your server.

Every call to your API goes through the APIHiver gateway. This page explains how to point the gateway at your server, how to make sure only the gateway can call it, and what the gateway adds to each request.

Base URL

Set on the General tab. It's the address of your server, for example:

https://api.example.com
http://203.0.113.10:8080/v1 (plain HTTP with an IP address and port is fine)

The gateway appends each endpoint's path to it. Consumers never see your base URL: they always call https://<your-slug>.p.apihiver.com, and APIHiver provides the HTTPS certificate for that address.

Secret headers and parameters

Without protection, anyone who discovers your base URL could call your server directly and skip your pricing. Prevent that with a secret:

Open Gateway → Secret Headers & Parameters and add one, for example a header named X-Proxy-Secret with a long random value.
The gateway attaches it to every request it forwards to you. Consumers never see it.
On your server, reject any request that doesn't carry the right value:

# FastAPI example
from fastapi import Header, HTTPException

def require_secret(x_proxy_secret: str = Header(None)):
    if x_proxy_secret != os.environ["PROXY_SECRET"]:
        raise HTTPException(401, "Call this API through APIHiver")

A secret can be sent as a header or as a query parameter. Values are write-only: once saved, they're stored encrypted and only revealed to you on request. To rotate a secret, update the value here and on your server at the same time.

Request configurations

Setting	What it does	Limit
Request size limit	Largest request body the gateway will forward. Bigger requests get `413 REQUEST_TOO_LARGE` without reaching you.	Up to 50 MB (the default)
Proxy timeout	How long the gateway waits for your server to answer before returning `502 BAD_GATEWAY`.	Up to 180 seconds (the default)

Lower the size limit if your API never needs big uploads. Raise the timeout only for slow jobs such as video processing.

What the gateway sends you

Along with the consumer's own headers, parameters and body, each forwarded request carries:

Header	Value
`X-APIHiver-Request-Id`	Unique ID of this call. Log it: consumers quote it when asking for help.
`X-APIHiver-Consumer-Id`	The calling user's ID
`X-APIHiver-Consumer-Username`	The calling user's username
`X-APIHiver-Subscription-Id`	The subscription the call is billed to
`X-APIHiver-Plan`	The name of the consumer's plan, for example `Pro`
your secret	Whatever you configured above

Use these to build per-user or per-plan behaviour on your side, without handling keys yourself. The consumer's X-API-Key is removed before the request reaches you.

What the gateway enforces for you

Before your server sees a request, the gateway has already checked the API key, the subscription (including whether you've blocked that subscriber), that the endpoint exists in your Definitions, the plan's rate limit, monthly quota and concurrency limit, and the request size. Calls that fail any check are answered by the gateway and never reach you. See Error codes.