API reference

Firewall

A firewall per project, run by the edge servers before the code: always-on flood and malformed-request protection, and custom rules on address, country, method, path, host and headers that deny, allow, log or rate limit. Checks are free; stopped requests are not billed.

GET/v1/functions/{name}/firewall

The firewall#

Status (normal, or mitigating when a system mitigation stopped a request in the last ten minutes), the always-on system mitigations, the custom rules in the order they run, the plan's limits, the rule model and the country data's source and attribution.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200Firewall

activeboolean
statusstring
one of normal, mitigating
systemFirewallMitigation[]
- idstring
  one of sys:flood, sys:malformed
- nameobject
- descriptionobject
- activeboolean
- hits_10minteger
  requests it stopped in the last ten minutes
rulesFirewallRule[]
- idstring
  pattern ^fwr_[a-z0-9]{12}$
- positioninteger
  0 runs first
- namestring
  1–80 characters
- descriptionstring
  up to 500 characters
- enabledboolean
  default true
- ifFirewallCondition[][]
  groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
  1–… items
- actionstring
  deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
  one of deny, allow, log, rate_limit
- rateFirewallRate
- created_atstring (date-time)
- updated_atstring (date-time)
- created_bystring
  an email or key name
- updated_bystring
publishedboolean
false when no rule is enabled
limitsobject
- planstring
- custom_rulesinteger
- rate_limit_rulesinteger
- conditions_per_ruleinteger
- values_per_conditioninteger
- custom_rules_usedinteger
- rate_limit_rules_usedinteger
modelobject
- fieldsstring[]
- actionsstring[]
- windowsinteger[]
geoipobject
where the country of an address comes from: DB-IP IP to Country Lite, CC BY 4.0 (IP geolocation by DB-IP)
- sourcestring
- licensestring
- attributionstring
- urlstring

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/functions/my-api/firewall" \
  -H "Authorization: Bearer $KEY"

POST/v1/functions/{name}/firewall/rules

Add a firewall rule#

Add a custom rule at position (0 runs first; default last). Published at once to every server; nothing restarts. The plan caps the rules and the rate limit rules per project.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

namestringrequired
1–80 characters
descriptionstring
up to 500 characters
enabledboolean
default true
ifFirewallCondition[][]required
groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
1–… items
- fieldstringrequired
  one of ip, country, method, path, host, user_agent, header
- opstring
  ip, country, method: in; path, host, user_agent, header: eq, starts, ends, contains, in, re; header also exists
  one of eq, starts, ends, contains, in, re, exists · default "in"
- valuesstring[]
  ip: addresses or CIDR ranges (IPv4, IPv6); country: two-letter codes; method: GET, POST…; one value except for in; none for exists. re: 256 characters at most, no lookaround or backreferences, (?i) to ignore case
- namestring
  header: the header's name
- negboolean
actionstringrequired
deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
one of deny, allow, log, rate_limit
rateFirewallRate
- limitintegerrequired
  requests per window, per key
  1–1000000
- windowinteger
  seconds
  one of 10, 60, 300, 600, 3600 · default 60
- keystring
  ip or header:<name>
  default "ip"
- thenstring
  above the limit: 429, or only log
  one of deny, log · default "deny"
positioninteger
0 runs first; default last
at least 0

Response

201FirewallRule

idstring
pattern ^fwr_[a-z0-9]{12}$
positioninteger
0 runs first
namestring
1–80 characters
descriptionstring
up to 500 characters
enabledboolean
default true
ifFirewallCondition[][]
groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
1–… items
- fieldstringrequired
  one of ip, country, method, path, host, user_agent, header
- opstring
  ip, country, method: in; path, host, user_agent, header: eq, starts, ends, contains, in, re; header also exists
  one of eq, starts, ends, contains, in, re, exists · default "in"
- valuesstring[]
  ip: addresses or CIDR ranges (IPv4, IPv6); country: two-letter codes; method: GET, POST…; one value except for in; none for exists. re: 256 characters at most, no lookaround or backreferences, (?i) to ignore case
- namestring
  header: the header's name
- negboolean
actionstring
deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
one of deny, allow, log, rate_limit
rateFirewallRate
- limitintegerrequired
  requests per window, per key
  1–1000000
- windowinteger
  seconds
  one of 10, 60, 300, 600, 3600 · default 60
- keystring
  ip or header:<name>
  default "ip"
- thenstring
  above the limit: 429, or only log
  one of deny, log · default "deny"
created_atstring (date-time)
updated_atstring (date-time)
created_bystring
an email or key name
updated_bystring

Errors

Status	Description
400	`firewall_bad_rule`, `firewall_bad_condition`, `firewall_bad_regex`, `firewall_bad_rate`, `firewall_bad_position`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
409	`firewall_limit`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/firewall/rules" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"my-api","if":[[{"field":"ip","op":"in","values":["…"],"name":"my-api","neg":true}]],"action":"deny"}'

GET/v1/functions/{name}/firewall/rules/{id}

One firewall rule#

The rule.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstringpathrequired
the rule's id
pattern ^fwr_[a-z0-9]{12}$

Response

200FirewallRule

idstring
pattern ^fwr_[a-z0-9]{12}$
positioninteger
0 runs first
namestring
1–80 characters
descriptionstring
up to 500 characters
enabledboolean
default true
ifFirewallCondition[][]
groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
1–… items
- fieldstringrequired
  one of ip, country, method, path, host, user_agent, header
- opstring
  ip, country, method: in; path, host, user_agent, header: eq, starts, ends, contains, in, re; header also exists
  one of eq, starts, ends, contains, in, re, exists · default "in"
- valuesstring[]
  ip: addresses or CIDR ranges (IPv4, IPv6); country: two-letter codes; method: GET, POST…; one value except for in; none for exists. re: 256 characters at most, no lookaround or backreferences, (?i) to ignore case
- namestring
  header: the header's name
- negboolean
actionstring
deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
one of deny, allow, log, rate_limit
rateFirewallRate
- limitintegerrequired
  requests per window, per key
  1–1000000
- windowinteger
  seconds
  one of 10, 60, 300, 600, 3600 · default 60
- keystring
  ip or header:<name>
  default "ip"
- thenstring
  above the limit: 429, or only log
  one of deny, log · default "deny"
created_atstring (date-time)
updated_atstring (date-time)
created_bystring
an email or key name
updated_bystring

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/functions/my-api/firewall/rules/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/functions/{name}/firewall/rules/{id}

Delete a firewall rule#

Delete a custom rule; the ones after it move up.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstringpathrequired
the rule's id
pattern ^fwr_[a-z0-9]{12}$

Response

200FirewallDeleted

deletedstring
the rule's id

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/functions/my-api/firewall/rules/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/functions/{name}/firewall/rules/{id}

Change a firewall rule#

Any of the rule's fields; the others stay. {"enabled": false} switches it off; if replaces its conditions.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstringpathrequired
the rule's id
pattern ^fwr_[a-z0-9]{12}$

Request body`application/json`

namestring
1–80 characters
descriptionstring
up to 500 characters
enabledboolean
default true
ifFirewallCondition[][]
groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
1–… items
- fieldstringrequired
  one of ip, country, method, path, host, user_agent, header
- opstring
  ip, country, method: in; path, host, user_agent, header: eq, starts, ends, contains, in, re; header also exists
  one of eq, starts, ends, contains, in, re, exists · default "in"
- valuesstring[]
  ip: addresses or CIDR ranges (IPv4, IPv6); country: two-letter codes; method: GET, POST…; one value except for in; none for exists. re: 256 characters at most, no lookaround or backreferences, (?i) to ignore case
- namestring
  header: the header's name
- negboolean
actionstring
deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
one of deny, allow, log, rate_limit
rateFirewallRate
- limitintegerrequired
  requests per window, per key
  1–1000000
- windowinteger
  seconds
  one of 10, 60, 300, 600, 3600 · default 60
- keystring
  ip or header:<name>
  default "ip"
- thenstring
  above the limit: 429, or only log
  one of deny, log · default "deny"

Response

200FirewallRule

idstring
pattern ^fwr_[a-z0-9]{12}$
positioninteger
0 runs first
namestring
1–80 characters
descriptionstring
up to 500 characters
enabledboolean
default true
ifFirewallCondition[][]
groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
1–… items
- fieldstringrequired
  one of ip, country, method, path, host, user_agent, header
- opstring
  ip, country, method: in; path, host, user_agent, header: eq, starts, ends, contains, in, re; header also exists
  one of eq, starts, ends, contains, in, re, exists · default "in"
- valuesstring[]
  ip: addresses or CIDR ranges (IPv4, IPv6); country: two-letter codes; method: GET, POST…; one value except for in; none for exists. re: 256 characters at most, no lookaround or backreferences, (?i) to ignore case
- namestring
  header: the header's name
- negboolean
actionstring
deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
one of deny, allow, log, rate_limit
rateFirewallRate
- limitintegerrequired
  requests per window, per key
  1–1000000
- windowinteger
  seconds
  one of 10, 60, 300, 600, 3600 · default 60
- keystring
  ip or header:<name>
  default "ip"
- thenstring
  above the limit: 429, or only log
  one of deny, log · default "deny"
created_atstring (date-time)
updated_atstring (date-time)
created_bystring
an email or key name
updated_bystring

Errors

Status	Description
400	`firewall_bad_rule`, `firewall_bad_condition`, `firewall_bad_regex`, `firewall_bad_rate`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
409	`firewall_limit`
500	`internal`: an unexpected failure

Example

curl -X PATCH "https://api.ibel.ai/v1/functions/my-api/firewall/rules/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"my-api","description":"…","enabled":true,"if":[[{"field":"ip","op":"in","values":["…"],"name":"my-api","neg":true}]],"action":"deny","rate":{"limit":1,"window":60,"key":"ip","then":"deny"}}'

PUT/v1/functions/{name}/firewall/order

Reorder the firewall rules#

Every rule id of the project once, in the new order (the first runs first). Answers with the firewall.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

idsstring[]required
every rule id once, in the new order

Response

200Firewall

activeboolean
statusstring
one of normal, mitigating
systemFirewallMitigation[]
- idstring
  one of sys:flood, sys:malformed
- nameobject
- descriptionobject
- activeboolean
- hits_10minteger
  requests it stopped in the last ten minutes
rulesFirewallRule[]
- idstring
  pattern ^fwr_[a-z0-9]{12}$
- positioninteger
  0 runs first
- namestring
  1–80 characters
- descriptionstring
  up to 500 characters
- enabledboolean
  default true
- ifFirewallCondition[][]
  groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
  1–… items
- actionstring
  deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
  one of deny, allow, log, rate_limit
- rateFirewallRate
- created_atstring (date-time)
- updated_atstring (date-time)
- created_bystring
  an email or key name
- updated_bystring
publishedboolean
false when no rule is enabled
limitsobject
- planstring
- custom_rulesinteger
- rate_limit_rulesinteger
- conditions_per_ruleinteger
- values_per_conditioninteger
- custom_rules_usedinteger
- rate_limit_rules_usedinteger
modelobject
- fieldsstring[]
- actionsstring[]
- windowsinteger[]
geoipobject
where the country of an address comes from: DB-IP IP to Country Lite, CC BY 4.0 (IP geolocation by DB-IP)
- sourcestring
- licensestring
- attributionstring
- urlstring

Errors

Status	Description
400	`firewall_bad_order`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl -X PUT "https://api.ibel.ai/v1/functions/my-api/firewall/order" \
  -H "Authorization: Bearer $KEY" \
  -d '{"ids":["…"]}'

POST/v1/functions/{name}/firewall/check

Test a request against the firewall#

What the rules would do with a request; nothing is sent to the project. Rate limits are not counted (one request is never over a limit).

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

ipstringrequired
countrystring
two letters
methodstring
default "GET"
pathstring
default "/"
hoststring
user_agentstring
headersmap of string

Response

200FirewallVerdict

outcomestring
one of allowed, denied, rate_limited
rulestring | null
rule_namestring | null
loggedobject[]
- idstring
- namestring | null
statusinteger
403, 429, or 0 when allowed
notestring

Errors

Status	Description
400	`firewall_bad_check`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/firewall/check" \
  -H "Authorization: Bearer $KEY" \
  -d '{"ip":"…"}'

GET/v1/functions/{name}/firewall/metrics

Firewall metrics#

Requests allowed, denied, logged and rate limited over time, hits per rule (every rule and system mitigation, with no hits too), and the top 20 addresses and countries the firewall stopped. Counts are kept 31 days.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
rangestringquery
1h (1-minute steps), 24h (15 minutes, the default) or 7d (2 hours)
one of 1h, 24h, 7d · default "24h"

Response

200FirewallMetrics

rangestring
stepstring
totalsobject
- allowedinteger
- deniedinteger
- loggedinteger
- rate_limitedinteger
seriesobject[]
- tstring (date-time)
- allowedinteger
- deniedinteger
- loggedinteger
- rate_limitedinteger
rulesobject[]
- idstring
- namestring | null
- systemboolean
- hitsinteger
- outcomesmap of integer
- seriesobject[]
ipsobject[]
- ipstring
- countrystring | null
- outcomestring
- ninteger
countriesobject[]
- countrystring
- ninteger
notestring

Errors

Status	Description
400	`bad_range`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/functions/my-api/firewall/metrics" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/firewall/audit

Firewall changes#

The firewall's rule changes, newest first, with who, when and the before and after. Page with before (the next of the last page).

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
beforeintegerquery
only entries older than this id
at least 1
limitintegerquery
how many (default 50)
1–200 · default 50

Response

200FirewallAudit

entriesobject[]
- idinteger
- atstring (date-time)
- actorstring
- actionstring
  one of rule.create, rule.update, rule.enable, rule.disable, rule.delete, rule.reorder
- rule_idstring
- namestring
- beforeany
- afterany
nextinteger | null
the before of the next page

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/functions/my-api/firewall/audit" \
  -H "Authorization: Bearer $KEY"

GET/v1/apps/{name}/firewall

The firewall#

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200Firewall

activeboolean
statusstring
one of normal, mitigating
systemFirewallMitigation[]
- idstring
  one of sys:flood, sys:malformed
- nameobject
- descriptionobject
- activeboolean
- hits_10minteger
  requests it stopped in the last ten minutes
rulesFirewallRule[]
- idstring
  pattern ^fwr_[a-z0-9]{12}$
- positioninteger
  0 runs first
- namestring
  1–80 characters
- descriptionstring
  up to 500 characters
- enabledboolean
  default true
- ifFirewallCondition[][]
  groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
  1–… items
- actionstring
  deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
  one of deny, allow, log, rate_limit
- rateFirewallRate
- created_atstring (date-time)
- updated_atstring (date-time)
- created_bystring
  an email or key name
- updated_bystring
publishedboolean
false when no rule is enabled
limitsobject
- planstring
- custom_rulesinteger
- rate_limit_rulesinteger
- conditions_per_ruleinteger
- values_per_conditioninteger
- custom_rules_usedinteger
- rate_limit_rules_usedinteger
modelobject
- fieldsstring[]
- actionsstring[]
- windowsinteger[]
geoipobject
where the country of an address comes from: DB-IP IP to Country Lite, CC BY 4.0 (IP geolocation by DB-IP)
- sourcestring
- licensestring
- attributionstring
- urlstring

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/apps/my-api/firewall" \
  -H "Authorization: Bearer $KEY"

POST/v1/apps/{name}/firewall/rules

Add a firewall rule#

Add a custom rule at position (0 runs first; default last). Published at once to every server; nothing restarts. The plan caps the rules and the rate limit rules per project.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

namestringrequired
1–80 characters
descriptionstring
up to 500 characters
enabledboolean
default true
ifFirewallCondition[][]required
groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
1–… items
- fieldstringrequired
  one of ip, country, method, path, host, user_agent, header
- opstring
  ip, country, method: in; path, host, user_agent, header: eq, starts, ends, contains, in, re; header also exists
  one of eq, starts, ends, contains, in, re, exists · default "in"
- valuesstring[]
  ip: addresses or CIDR ranges (IPv4, IPv6); country: two-letter codes; method: GET, POST…; one value except for in; none for exists. re: 256 characters at most, no lookaround or backreferences, (?i) to ignore case
- namestring
  header: the header's name
- negboolean
actionstringrequired
deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
one of deny, allow, log, rate_limit
rateFirewallRate
- limitintegerrequired
  requests per window, per key
  1–1000000
- windowinteger
  seconds
  one of 10, 60, 300, 600, 3600 · default 60
- keystring
  ip or header:<name>
  default "ip"
- thenstring
  above the limit: 429, or only log
  one of deny, log · default "deny"
positioninteger
0 runs first; default last
at least 0

Response

201FirewallRule

idstring
pattern ^fwr_[a-z0-9]{12}$
positioninteger
0 runs first
namestring
1–80 characters
descriptionstring
up to 500 characters
enabledboolean
default true
ifFirewallCondition[][]
groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
1–… items
- fieldstringrequired
  one of ip, country, method, path, host, user_agent, header
- opstring
  ip, country, method: in; path, host, user_agent, header: eq, starts, ends, contains, in, re; header also exists
  one of eq, starts, ends, contains, in, re, exists · default "in"
- valuesstring[]
  ip: addresses or CIDR ranges (IPv4, IPv6); country: two-letter codes; method: GET, POST…; one value except for in; none for exists. re: 256 characters at most, no lookaround or backreferences, (?i) to ignore case
- namestring
  header: the header's name
- negboolean
actionstring
deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
one of deny, allow, log, rate_limit
rateFirewallRate
- limitintegerrequired
  requests per window, per key
  1–1000000
- windowinteger
  seconds
  one of 10, 60, 300, 600, 3600 · default 60
- keystring
  ip or header:<name>
  default "ip"
- thenstring
  above the limit: 429, or only log
  one of deny, log · default "deny"
created_atstring (date-time)
updated_atstring (date-time)
created_bystring
an email or key name
updated_bystring

Errors

Status	Description
400	`firewall_bad_rule`, `firewall_bad_condition`, `firewall_bad_regex`, `firewall_bad_rate`, `firewall_bad_position`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
409	`firewall_limit`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/apps/my-api/firewall/rules" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"my-api","if":[[{"field":"ip","op":"in","values":["…"],"name":"my-api","neg":true}]],"action":"deny"}'

GET/v1/apps/{name}/firewall/rules/{id}

One firewall rule#

The rule.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstringpathrequired
the rule's id
pattern ^fwr_[a-z0-9]{12}$

Response

200FirewallRule

idstring
pattern ^fwr_[a-z0-9]{12}$
positioninteger
0 runs first
namestring
1–80 characters
descriptionstring
up to 500 characters
enabledboolean
default true
ifFirewallCondition[][]
groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
1–… items
- fieldstringrequired
  one of ip, country, method, path, host, user_agent, header
- opstring
  ip, country, method: in; path, host, user_agent, header: eq, starts, ends, contains, in, re; header also exists
  one of eq, starts, ends, contains, in, re, exists · default "in"
- valuesstring[]
  ip: addresses or CIDR ranges (IPv4, IPv6); country: two-letter codes; method: GET, POST…; one value except for in; none for exists. re: 256 characters at most, no lookaround or backreferences, (?i) to ignore case
- namestring
  header: the header's name
- negboolean
actionstring
deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
one of deny, allow, log, rate_limit
rateFirewallRate
- limitintegerrequired
  requests per window, per key
  1–1000000
- windowinteger
  seconds
  one of 10, 60, 300, 600, 3600 · default 60
- keystring
  ip or header:<name>
  default "ip"
- thenstring
  above the limit: 429, or only log
  one of deny, log · default "deny"
created_atstring (date-time)
updated_atstring (date-time)
created_bystring
an email or key name
updated_bystring

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/apps/my-api/firewall/rules/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/apps/{name}/firewall/rules/{id}

Delete a firewall rule#

Delete a custom rule; the ones after it move up.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstringpathrequired
the rule's id
pattern ^fwr_[a-z0-9]{12}$

Response

200FirewallDeleted

deletedstring
the rule's id

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/apps/my-api/firewall/rules/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/apps/{name}/firewall/rules/{id}

Change a firewall rule#

Any of the rule's fields; the others stay. {"enabled": false} switches it off; if replaces its conditions.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstringpathrequired
the rule's id
pattern ^fwr_[a-z0-9]{12}$

Request body`application/json`

namestring
1–80 characters
descriptionstring
up to 500 characters
enabledboolean
default true
ifFirewallCondition[][]
groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
1–… items
- fieldstringrequired
  one of ip, country, method, path, host, user_agent, header
- opstring
  ip, country, method: in; path, host, user_agent, header: eq, starts, ends, contains, in, re; header also exists
  one of eq, starts, ends, contains, in, re, exists · default "in"
- valuesstring[]
  ip: addresses or CIDR ranges (IPv4, IPv6); country: two-letter codes; method: GET, POST…; one value except for in; none for exists. re: 256 characters at most, no lookaround or backreferences, (?i) to ignore case
- namestring
  header: the header's name
- negboolean
actionstring
deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
one of deny, allow, log, rate_limit
rateFirewallRate
- limitintegerrequired
  requests per window, per key
  1–1000000
- windowinteger
  seconds
  one of 10, 60, 300, 600, 3600 · default 60
- keystring
  ip or header:<name>
  default "ip"
- thenstring
  above the limit: 429, or only log
  one of deny, log · default "deny"

Response

200FirewallRule

idstring
pattern ^fwr_[a-z0-9]{12}$
positioninteger
0 runs first
namestring
1–80 characters
descriptionstring
up to 500 characters
enabledboolean
default true
ifFirewallCondition[][]
groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
1–… items
- fieldstringrequired
  one of ip, country, method, path, host, user_agent, header
- opstring
  ip, country, method: in; path, host, user_agent, header: eq, starts, ends, contains, in, re; header also exists
  one of eq, starts, ends, contains, in, re, exists · default "in"
- valuesstring[]
  ip: addresses or CIDR ranges (IPv4, IPv6); country: two-letter codes; method: GET, POST…; one value except for in; none for exists. re: 256 characters at most, no lookaround or backreferences, (?i) to ignore case
- namestring
  header: the header's name
- negboolean
actionstring
deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
one of deny, allow, log, rate_limit
rateFirewallRate
- limitintegerrequired
  requests per window, per key
  1–1000000
- windowinteger
  seconds
  one of 10, 60, 300, 600, 3600 · default 60
- keystring
  ip or header:<name>
  default "ip"
- thenstring
  above the limit: 429, or only log
  one of deny, log · default "deny"
created_atstring (date-time)
updated_atstring (date-time)
created_bystring
an email or key name
updated_bystring

Errors

Status	Description
400	`firewall_bad_rule`, `firewall_bad_condition`, `firewall_bad_regex`, `firewall_bad_rate`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
409	`firewall_limit`
500	`internal`: an unexpected failure

Example

curl -X PATCH "https://api.ibel.ai/v1/apps/my-api/firewall/rules/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"my-api","description":"…","enabled":true,"if":[[{"field":"ip","op":"in","values":["…"],"name":"my-api","neg":true}]],"action":"deny","rate":{"limit":1,"window":60,"key":"ip","then":"deny"}}'

PUT/v1/apps/{name}/firewall/order

Reorder the firewall rules#

Every rule id of the project once, in the new order (the first runs first). Answers with the firewall.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

idsstring[]required
every rule id once, in the new order

Response

200Firewall

activeboolean
statusstring
one of normal, mitigating
systemFirewallMitigation[]
- idstring
  one of sys:flood, sys:malformed
- nameobject
- descriptionobject
- activeboolean
- hits_10minteger
  requests it stopped in the last ten minutes
rulesFirewallRule[]
- idstring
  pattern ^fwr_[a-z0-9]{12}$
- positioninteger
  0 runs first
- namestring
  1–80 characters
- descriptionstring
  up to 500 characters
- enabledboolean
  default true
- ifFirewallCondition[][]
  groups of conditions: the rule matches when every condition of at least one group matches (a flat list is one group)
  1–… items
- actionstring
  deny: 403, the code does not run; allow: skip the rules after it; log: count and go on; rate_limit: needs rate
  one of deny, allow, log, rate_limit
- rateFirewallRate
- created_atstring (date-time)
- updated_atstring (date-time)
- created_bystring
  an email or key name
- updated_bystring
publishedboolean
false when no rule is enabled
limitsobject
- planstring
- custom_rulesinteger
- rate_limit_rulesinteger
- conditions_per_ruleinteger
- values_per_conditioninteger
- custom_rules_usedinteger
- rate_limit_rules_usedinteger
modelobject
- fieldsstring[]
- actionsstring[]
- windowsinteger[]
geoipobject
where the country of an address comes from: DB-IP IP to Country Lite, CC BY 4.0 (IP geolocation by DB-IP)
- sourcestring
- licensestring
- attributionstring
- urlstring

Errors

Status	Description
400	`firewall_bad_order`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl -X PUT "https://api.ibel.ai/v1/apps/my-api/firewall/order" \
  -H "Authorization: Bearer $KEY" \
  -d '{"ids":["…"]}'

POST/v1/apps/{name}/firewall/check

Test a request against the firewall#

What the rules would do with a request; nothing is sent to the project. Rate limits are not counted (one request is never over a limit).

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

ipstringrequired
countrystring
two letters
methodstring
default "GET"
pathstring
default "/"
hoststring
user_agentstring
headersmap of string

Response

200FirewallVerdict

outcomestring
one of allowed, denied, rate_limited
rulestring | null
rule_namestring | null
loggedobject[]
- idstring
- namestring | null
statusinteger
403, 429, or 0 when allowed
notestring

Errors

Status	Description
400	`firewall_bad_check`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/apps/my-api/firewall/check" \
  -H "Authorization: Bearer $KEY" \
  -d '{"ip":"…"}'

GET/v1/apps/{name}/firewall/metrics

Firewall metrics#

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
rangestringquery
1h (1-minute steps), 24h (15 minutes, the default) or 7d (2 hours)
one of 1h, 24h, 7d · default "24h"

Response

200FirewallMetrics

rangestring
stepstring
totalsobject
- allowedinteger
- deniedinteger
- loggedinteger
- rate_limitedinteger
seriesobject[]
- tstring (date-time)
- allowedinteger
- deniedinteger
- loggedinteger
- rate_limitedinteger
rulesobject[]
- idstring
- namestring | null
- systemboolean
- hitsinteger
- outcomesmap of integer
- seriesobject[]
ipsobject[]
- ipstring
- countrystring | null
- outcomestring
- ninteger
countriesobject[]
- countrystring
- ninteger
notestring

Errors

Status	Description
400	`bad_range`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/apps/my-api/firewall/metrics" \
  -H "Authorization: Bearer $KEY"

GET/v1/apps/{name}/firewall/audit

Firewall changes#

The firewall's rule changes, newest first, with who, when and the before and after. Page with before (the next of the last page).

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
beforeintegerquery
only entries older than this id
at least 1
limitintegerquery
how many (default 50)
1–200 · default 50

Response

200FirewallAudit

entriesobject[]
- idinteger
- atstring (date-time)
- actorstring
- actionstring
  one of rule.create, rule.update, rule.enable, rule.disable, rule.delete, rule.reorder
- rule_idstring
- namestring
- beforeany
- afterany
nextinteger | null
the before of the next page

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	`not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/apps/my-api/firewall/audit" \
  -H "Authorization: Bearer $KEY"

The firewall#

Parameters

Response

Errors

Example

Add a firewall rule#

Parameters

Request bodyapplication/json

Response

Errors

Example

One firewall rule#

Parameters

Response

Errors

Example

Delete a firewall rule#

Parameters

Response

Errors

Example

Change a firewall rule#

Parameters

Request bodyapplication/json

Response

Errors

Example

Reorder the firewall rules#

Parameters

Request bodyapplication/json

Response

Errors

Example

Test a request against the firewall#

Parameters

Request bodyapplication/json

Response

Errors

Example

Firewall metrics#

Parameters

Response

Errors

Example

Firewall changes#

Parameters

Response

Errors

Example

The firewall#

Parameters

Response

Errors

Example

Add a firewall rule#

Parameters

Request bodyapplication/json

Response

Errors

Example

One firewall rule#

Parameters

Response

Errors

Example

Delete a firewall rule#

Parameters

Response

Errors

Example

Change a firewall rule#

Parameters

Request bodyapplication/json

Response

Errors

Example

Reorder the firewall rules#

Parameters

Request bodyapplication/json

Response

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`