Authentication

The Authorization header

Send your API key as a bearer token in the Authorization header of every request.

Authorization: Bearer <api-key>

A key in the URL or in the query string is not accepted. That keeps keys out of access logs, proxies and browser history.

Server-to-server only

TerraRelay is meant for server-to-server use. Never put a key in browser code, a JavaScript app or a mobile app: anyone can read it there. Call TerraRelay from your own backend and let your clients talk to that.

IP rules

You can limit a key to specific IP addresses. A request with that key from any other address is refused with 403. Use IP rules for keys that are only used from servers with a fixed address.

Rotate a key

To rotate a key without downtime:

1. Create a new key in the same project.
2. Deploy the new key to your servers.
3. Revoke the old key.

A project can have several keys at the same time, so the old and the new key both work during the switch.

401 or 403

• 401: the key is missing, unknown, revoked or expired. Check that the header is present and that the key is still active.
• 403: the key is valid, but the request comes from outside the key’s IP rules.

See Errors for all error responses.