Gateway

Policies run in order, and the first one that blocks a request ends evaluation. Deployments take a copy of the policies when they're created, so changes reach traffic with the next deployment. See Gateway.

List policies

POST /v1/gateway.listPolicies

Returns an environment's policies in the order they run.

Permissions: the key needs one of environment.*.read_policies, environment.<environment_id>.read_policies.

Request

Field	Type	Description
`project`	string, required	The project, by ID or slug. 3 to 255 characters.
`app`	string, required	The app, by ID or slug. 3 to 255 characters.
`environment`	string, required	The environment: `production`, `preview`, or its ID. 3 to 255 characters.

curl -X POST https://api.teral.dev/v1/gateway.listPolicies \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web",
    "environment": "production"
  }'

Response

On success the status is 200 OK. The fields in data:

Field	Type	Description
`id`	string	The policy's ID. It changes whenever `gateway.setPolicies` replaces the list.
`name`	string	The policy's name. 1 to 256 characters.
`enabled`	boolean	Whether it runs. Disabled policies are kept but skipped.
`match`	object[]	The conditions. All of them must match for the policy to apply. Missing or empty means every request. At most 10 items.
`match[].path`	object	Matches the request path, without the query string.
`match[].path.path`	object	How to compare. Set exactly one of `exact`, `prefix` or `regex`.
`match[].path.path.exact`	string	Matches the exact value. 1 to 1024 characters.
`match[].path.path.prefix`	string	Matches values that start with this. 1 to 1024 characters.
`match[].path.path.regex`	string	Matches an RE2 regular expression. Invalid ones are rejected. 1 to 1024 characters.
`match[].path.path.ignoreCase`	boolean	Ignore upper and lower case.
`match[].method`	object	Matches the request method.
`match[].method.methods`	string[]	The methods to match, such as `["POST", "DELETE"]`. At least 1 items.
`match[].header`	object	Matches a request header. Set exactly one of `present` or `value`.
`match[].header.name`	string	The header's name. Not case sensitive. 1 to 256 characters.
`match[].header.present`	boolean	`true` matches whenever it's there, whatever its value. One of `true`.
`match[].header.value`	object	How to compare the header's value. Set exactly one of `exact`, `prefix` or `regex`.
`match[].header.value.exact`	string	Matches the exact value. 1 to 1024 characters.
`match[].header.value.prefix`	string	Matches values that start with this. 1 to 1024 characters.
`match[].header.value.regex`	string	Matches an RE2 regular expression. Invalid ones are rejected. 1 to 1024 characters.
`match[].header.value.ignoreCase`	boolean	Ignore upper and lower case.
`match[].queryParam`	object	Matches a query parameter. Set exactly one of `present` or `value`.
`match[].queryParam.name`	string	The parameter's name. Case sensitive. 1 to 256 characters.
`match[].queryParam.present`	boolean	`true` matches whenever it's there, whatever its value. One of `true`.
`match[].queryParam.value`	object	How to compare the parameter's value. Set exactly one of `exact`, `prefix` or `regex`.
`match[].queryParam.value.exact`	string	Matches the exact value. 1 to 1024 characters.
`match[].queryParam.value.prefix`	string	Matches values that start with this. 1 to 1024 characters.
`match[].queryParam.value.regex`	string	Matches an RE2 regular expression. Invalid ones are rejected. 1 to 1024 characters.
`match[].queryParam.value.ignoreCase`	boolean	Ignore upper and lower case.
`match[].remoteIp`	object	Matches the client's IP address, taken from the connection, not from headers. Set exactly one of `in` or `notIn`.
`match[].remoteIp.in`	string[]	Matches clients inside any of these ranges, such as `203.0.113.0/24` or `203.0.113.7`. 1 to 100 items.
`match[].remoteIp.notIn`	string[]	Matches clients outside all of these ranges. 1 to 100 items.
`firewall`	object	Makes this a Firewall policy, which blocks matching requests with `403`.
`firewall.action`	string	What to do with a matching request. `ACTION_DENY` blocks it. One of `ACTION_DENY`.
`logging`	object	Makes this a Logging policy, which records more about matching requests.
`logging.requestHeaders`	boolean	Record request headers, the user agent and the client IP. Default `false`.
`logging.responseHeaders`	boolean	Record response headers. Default `false`.
`logging.requestBody`	boolean	Record the request body, up to a size limit. Default `false`.
`logging.responseBody`	boolean	Record the response body, up to a size limit. Default `false`.
`logging.query`	boolean	Record the query string. URLs sometimes contain secrets, so this is separate. Default `false`.

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.

Replace policies

POST /v1/gateway.setPolicies

Replaces all of an environment's policies with the list you send, in that order. An empty list removes them all. If any policy is invalid, nothing changes. Every policy gets a new ID.

Permissions: the key needs one of environment.*.set_policies, environment.<environment_id>.set_policies.

Request

Field	Type	Description
`project`	string, required	The project, by ID or slug. 3 to 255 characters.
`app`	string, required	The app, by ID or slug. 3 to 255 characters.
`environment`	string, required	The environment: `production`, `preview`, or its ID. 3 to 255 characters.
`policies`	object[], required	The complete list, in the order they should run. At most 50. At most 50 items.
`policies[].name`	string, required	A name to recognize the policy by. 1 to 256 characters.
`policies[].enabled`	boolean, required	Whether it runs. Disabled policies are kept but skipped.
`policies[].match`	object[]	The conditions. All of them must match for the policy to apply. Missing or empty means every request. At most 10 items.
`policies[].match[].path`	object	Matches the request path, without the query string.
`policies[].match[].path.path`	object, required	How to compare. Set exactly one of `exact`, `prefix` or `regex`.
`policies[].match[].path.path.exact`	string	Matches the exact value. 1 to 1024 characters.
`policies[].match[].path.path.prefix`	string	Matches values that start with this. 1 to 1024 characters.
`policies[].match[].path.path.regex`	string	Matches an RE2 regular expression. Invalid ones are rejected. 1 to 1024 characters.
`policies[].match[].path.path.ignoreCase`	boolean	Ignore upper and lower case.
`policies[].match[].method`	object	Matches the request method.
`policies[].match[].method.methods`	string[], required	The methods to match, such as `["POST", "DELETE"]`. At least 1 items.
`policies[].match[].header`	object	Matches a request header. Set exactly one of `present` or `value`.
`policies[].match[].header.name`	string, required	The header's name. Not case sensitive. 1 to 256 characters.
`policies[].match[].header.present`	boolean	`true` matches whenever it's there, whatever its value. One of `true`.
`policies[].match[].header.value`	object	How to compare the header's value. Set exactly one of `exact`, `prefix` or `regex`.
`policies[].match[].header.value.exact`	string	Matches the exact value. 1 to 1024 characters.
`policies[].match[].header.value.prefix`	string	Matches values that start with this. 1 to 1024 characters.
`policies[].match[].header.value.regex`	string	Matches an RE2 regular expression. Invalid ones are rejected. 1 to 1024 characters.
`policies[].match[].header.value.ignoreCase`	boolean	Ignore upper and lower case.
`policies[].match[].queryParam`	object	Matches a query parameter. Set exactly one of `present` or `value`.
`policies[].match[].queryParam.name`	string, required	The parameter's name. Case sensitive. 1 to 256 characters.
`policies[].match[].queryParam.present`	boolean	`true` matches whenever it's there, whatever its value. One of `true`.
`policies[].match[].queryParam.value`	object	How to compare the parameter's value. Set exactly one of `exact`, `prefix` or `regex`.
`policies[].match[].queryParam.value.exact`	string	Matches the exact value. 1 to 1024 characters.
`policies[].match[].queryParam.value.prefix`	string	Matches values that start with this. 1 to 1024 characters.
`policies[].match[].queryParam.value.regex`	string	Matches an RE2 regular expression. Invalid ones are rejected. 1 to 1024 characters.
`policies[].match[].queryParam.value.ignoreCase`	boolean	Ignore upper and lower case.
`policies[].match[].remoteIp`	object	Matches the client's IP address, taken from the connection, not from headers. Set exactly one of `in` or `notIn`.
`policies[].match[].remoteIp.in`	string[]	Matches clients inside any of these ranges, such as `203.0.113.0/24` or `203.0.113.7`. 1 to 100 items.
`policies[].match[].remoteIp.notIn`	string[]	Matches clients outside all of these ranges. 1 to 100 items.
`policies[].firewall`	object	Makes this a Firewall policy, which blocks matching requests with `403`.
`policies[].firewall.action`	string, required	What to do with a matching request. `ACTION_DENY` blocks it. One of `ACTION_DENY`.
`policies[].logging`	object	Makes this a Logging policy, which records more about matching requests.
`policies[].logging.requestHeaders`	boolean	Record request headers, the user agent and the client IP. Default `false`.
`policies[].logging.responseHeaders`	boolean	Record response headers. Default `false`.
`policies[].logging.requestBody`	boolean	Record the request body, up to a size limit. Default `false`.
`policies[].logging.responseBody`	boolean	Record the response body, up to a size limit. Default `false`.
`policies[].logging.query`	boolean	Record the query string. URLs sometimes contain secrets, so this is separate. Default `false`.

curl -X POST https://api.teral.dev/v1/gateway.setPolicies \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web",
    "environment": "production",
    "policies": [
      {
        "name": "Admin only from the office",
        "enabled": true,
        "match": [
          {
            "path": {
              "path": {
                "prefix": "/admin"
              }
            }
          },
          {
            "remoteIp": {
              "notIn": [
                "203.0.113.0/24"
              ]
            }
          }
        ],
        "firewall": {
          "action": "ACTION_DENY"
        }
      }
    ]
  }'

Response

On success the status is 200 OK.

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.

Update a policy

POST /v1/gateway.updatePolicy

Changes one policy and leaves the others and the order alone. Fields you leave out stay as they are. Sending firewall or logging replaces the policy's rule.

Permissions: the key needs one of environment.*.update_policy, environment.<environment_id>.update_policy.

Request

Field	Type	Description
`project`	string, required	The project, by ID or slug. 3 to 255 characters.
`app`	string, required	The app, by ID or slug. 3 to 255 characters.
`environment`	string, required	The environment: `production`, `preview`, or its ID. 3 to 255 characters.
`policyId`	string, required	The policy's ID, from `gateway.listPolicies`. 1 to 512 characters.
`name`	string	A new name. 1 to 256 characters.
`enabled`	boolean	Turns the policy on or off.
`match`	object[] or null	Replaces all conditions. `null` removes them, so the policy applies to every request. At most 10 items.
`match[].path`	object	Matches the request path, without the query string.
`match[].path.path`	object, required	How to compare. Set exactly one of `exact`, `prefix` or `regex`.
`match[].path.path.exact`	string	Matches the exact value. 1 to 1024 characters.
`match[].path.path.prefix`	string	Matches values that start with this. 1 to 1024 characters.
`match[].path.path.regex`	string	Matches an RE2 regular expression. Invalid ones are rejected. 1 to 1024 characters.
`match[].path.path.ignoreCase`	boolean	Ignore upper and lower case.
`match[].method`	object	Matches the request method.
`match[].method.methods`	string[], required	The methods to match, such as `["POST", "DELETE"]`. At least 1 items.
`match[].header`	object	Matches a request header. Set exactly one of `present` or `value`.
`match[].header.name`	string, required	The header's name. Not case sensitive. 1 to 256 characters.
`match[].header.present`	boolean	`true` matches whenever it's there, whatever its value. One of `true`.
`match[].header.value`	object	How to compare the header's value. Set exactly one of `exact`, `prefix` or `regex`.
`match[].header.value.exact`	string	Matches the exact value. 1 to 1024 characters.
`match[].header.value.prefix`	string	Matches values that start with this. 1 to 1024 characters.
`match[].header.value.regex`	string	Matches an RE2 regular expression. Invalid ones are rejected. 1 to 1024 characters.
`match[].header.value.ignoreCase`	boolean	Ignore upper and lower case.
`match[].queryParam`	object	Matches a query parameter. Set exactly one of `present` or `value`.
`match[].queryParam.name`	string, required	The parameter's name. Case sensitive. 1 to 256 characters.
`match[].queryParam.present`	boolean	`true` matches whenever it's there, whatever its value. One of `true`.
`match[].queryParam.value`	object	How to compare the parameter's value. Set exactly one of `exact`, `prefix` or `regex`.
`match[].queryParam.value.exact`	string	Matches the exact value. 1 to 1024 characters.
`match[].queryParam.value.prefix`	string	Matches values that start with this. 1 to 1024 characters.
`match[].queryParam.value.regex`	string	Matches an RE2 regular expression. Invalid ones are rejected. 1 to 1024 characters.
`match[].queryParam.value.ignoreCase`	boolean	Ignore upper and lower case.
`match[].remoteIp`	object	Matches the client's IP address, taken from the connection, not from headers. Set exactly one of `in` or `notIn`.
`match[].remoteIp.in`	string[]	Matches clients inside any of these ranges, such as `203.0.113.0/24` or `203.0.113.7`. 1 to 100 items.
`match[].remoteIp.notIn`	string[]	Matches clients outside all of these ranges. 1 to 100 items.
`firewall`	object	Makes this a Firewall policy, which blocks matching requests with `403`.
`firewall.action`	string, required	What to do with a matching request. `ACTION_DENY` blocks it. One of `ACTION_DENY`.
`logging`	object	Makes this a Logging policy, which records more about matching requests.
`logging.requestHeaders`	boolean	Record request headers, the user agent and the client IP. Default `false`.
`logging.responseHeaders`	boolean	Record response headers. Default `false`.
`logging.requestBody`	boolean	Record the request body, up to a size limit. Default `false`.
`logging.responseBody`	boolean	Record the response body, up to a size limit. Default `false`.
`logging.query`	boolean	Record the query string. URLs sometimes contain secrets, so this is separate. Default `false`.

curl -X POST https://api.teral.dev/v1/gateway.updatePolicy \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web",
    "environment": "production",
    "policyId": "pol_4f2…",
    "enabled": false
  }'

Response

On success the status is 200 OK.

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.

Gateway

List policiesCopy Anchor Link

RequestCopy Anchor Link

ResponseCopy Anchor Link

Replace policiesCopy Anchor Link

RequestCopy Anchor Link

ResponseCopy Anchor Link

Update a policyCopy Anchor Link

RequestCopy Anchor Link

ResponseCopy Anchor Link

On this page

List policies

Request

Response

Replace policies

Request

Response

Update a policy

Request

Response