Upstream Authentication & TLS
The API Gateway adds the upstream credential to each call itself, so agents and users never see it. Configure it in the Upstream card of the API's edit page.
Auth types
| Auth type | Settings | Secret field | Sent to the upstream as |
|---|---|---|---|
| None | — | — | No credential |
| Bearer token | — | Bearer token | Authorization: Bearer <token> |
| API key | Key name, send in Header or Query parameter | API key | X-API-Key: <key> (or your header name), or ?api_key=<key> |
| Basic | Username | Password | Authorization: Basic <base64(username:password)> |
| OAuth2 client credentials | Token URL, client ID, optional scope and audience | Client secret | Authorization: Bearer <access token> |
OAuth2 client credentials
The gateway requests an access token from your Token URL with grant_type=client_credentials, your client ID and secret (plus scope and audience if set), and uses it as a bearer token.
- Tokens are cached and reused until 60 seconds before they expire (using
expires_in, or 5 minutes if the token endpoint doesn't say), so the token endpoint isn't called on every request. - The Token URL passes the same network protections and host allow-list as the upstream.
- Changing the client ID, scope, audience or secret invalidates the cached token.
- If the token endpoint fails, calls return
502 upstream_auth_failed.
Secrets are never returned
The secret field (token, API key, password or client secret) is encrypted at rest and always shown as •••••••• after saving. Leave it unchanged to keep the current secret, or type a new value to replace it.
Custom CA and mutual TLS
Tick Custom CA or mutual TLS on the Upstream card for upstreams that use a private certificate authority or require a client certificate:
| Field | Use |
|---|---|
| CA certificate (PEM) | Trust an upstream whose server certificate is signed by your own CA |
| Client certificate (PEM) | The certificate the gateway presents for mutual TLS |
| Client private key (PEM) | The matching private key — stored encrypted, shown as •••••••• after saving |
Certificates are checked when you save, and an invalid PEM is rejected. The same TLS settings are used for the OAuth2 token request. TLS settings that can't be loaded at call time return 502 upstream_tls_config_invalid.
Secret rotation
Two actions in the Security card let you rotate secrets without pulling the API back to draft or re-approving it. They're available to lifecycle_manager, space_admin and admin, and each is recorded in the API's audit log.
| Action | What changes | Effect |
|---|---|---|
| Rotate gateway secret | The secret between Hrida.ai and its gateway | The old secret stops working immediately; the Tool Server entry is updated, so agents pick up the new one automatically |
| Rotate upstream credential | The upstream secret and/or the TLS client private key | The next call uses the new credential; nothing else about the API changes |
The same actions are available in the API:
POST /api/v1/api-definitions/{id}/rotate-gateway-secret
POST /api/v1/api-definitions/{id}/rotate-upstream-credential {"auth_key": "...", "tls_client_key": "...", "notes": "quarterly rotation"}
Related
- API Gateway — where the credential is applied in the pipeline
- Gateway Policy & Security — network protections and the host allow-list
- API Catalogs, Spaces & Roles — who can rotate secrets