Sterile Networks API

Overview

The Sterile Networks API covers what the dashboard does for your protected addresses: tunnels, the service rules and source rules on them, protection settings, attacks and traffic analytics.

Every endpoint takes and returns JSON. The endpoint pages are generated from the API's OpenAPI specification, so they always list the endpoints that exist. Where the specification does not yet describe an endpoint's parameters or response, the page says so instead of guessing.

Authentication

Every endpoint under /v1/api needs an API key, sent as a request header. Create one in your dashboard's settings. Endpoints under /v1/public need no key.

A key acts as the account that created it and reaches every tunnel in every workspace that account belongs to. A key is either read-only or read and write; a read-only key is refused on any endpoint that changes something.

• X-API-Key: <your_api_key>
• Or Authorization: Bearer <your_api_key>
• A key is shown once, when you create it. Store it then; a lost key can only be replaced.
• A key can be limited to specific source IP addresses. A request from any other address is refused with 403.

Your first request

List the tunnels your key can reach. Most other endpoints take a tunnel_id from this response.

curl --request GET \
  --url 'https://backend.sterile.network/v1/api/tunnels' \
  --header 'X-API-Key: <your_api_key>'

Errors

A failed request returns the matching HTTP status and a JSON body with ok set to false and a message written for a person. Show that message as it is: it says what happened and, where it applies, what to do next.

• 401: the key header is missing, or the key is not recognised.
• 403: the key is read-only and the endpoint changes something, or the key is not allowed from this IP address.
• 429: you have hit the endpoint's rate limit.

{
  "ok": false,
  "message": "This API key is read-only. Use a key with write scope to make changes."
}

Rate limits

Each endpoint has its own limit, counted per account over a rolling 60 seconds (per source IP address on public endpoints).

Endpoints that read allow 120 requests a minute. Endpoints that change something allow between 20 and 60 a minute, depending on the endpoint. Over the limit you get a 429; wait before retrying rather than retrying at once.