Authentication

Every public Gateway request uses an App API Key. The Host selects the chain, network, and protocol; the API Key selects the App. One valid Key can access enabled, routed Gateways that belong to that App.

Bearer authentication

Bearer authentication is recommended for server-side applications because it keeps the Key out of URLs and access logs:


curl 'https://ether-jsonrpc.<gateway-domain>' \
  -H 'Authorization: Bearer <app_api_key>' \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Authorization must contain exactly Bearer <key>.

Path Key

Put the Key in the first path segment when an SDK requires a complete RPC URL:


https://ether-jsonrpc.<gateway-domain>/<app_api_key>
https://tron-httpapi.<gateway-domain>/<app_api_key>/wallet/getnowblock

Path Keys are convenient but can appear in proxy access logs, browser history, and monitoring systems. Use them only when the complete URL is protected.

If a request includes both a Path Key and a Bearer Key, they must match exactly.

Unsupported credential locations

Do not send an App API Key in:

query parameters;
cookies;
custom headers;
a JSON-RPC request body.

Key states and rotation

Active: accepted normally.
Grace: the previous Key remains accepted during a rotation grace period.
Expired: no longer accepted after the grace period.
Revoked: invalid immediately.

Recommended rotation sequence: create the new Key, update every application instance, verify the new Key, then revoke the old Key. Do not revoke before clients have switched.

Authentication also fails when the App is disabled, the Account is inactive, or the Key is expired or revoked. JSON-RPC returns code -32001; TRON HTTP API returns HTTP 401.

Security guidance

Store Keys in a Secret Manager or runtime environment variable.
Never commit them to Git or embed them in frontend or mobile bundles.
Log an internal Key ID, not the complete Key or a URL containing it.
Rotate and revoke immediately after suspected exposure.