Skip to main content
POST
Change a BotShield Action

Authorizations

Authorization
string
header
required

Your secret server API key (bs_dev_… or bs_production_…) with Gates API access: the gates:write scope, granted in the Console under Settings → Developer Tools → API Keys. Without it every Gates API call answers gates_scope_required. The organization and environment always come from the key. Site keys are refused.

Body

application/json
actKey
string
required

The action's key (input is lower-cased).

Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$
Example:

"account-recovery"

name
string

Shown to the person on their card.

Required string length: 1 - 60
Example:

"You asked to recover your account."

staffCanSend
boolean

Your support team can send this to a customer. Its name is what the customer reads.

Example:

true

highValue
boolean

High-value. It starts only from your customer's signed-in session (your server naming the account by your own reference). It is refused by phone number and for staff sends (action_requires_signed_in).

Example:

true

Response

The action. NOTE: handler errors also arrive here (HTTP 200) as data.error — codes: invalid_key (401 — missing, malformed or inactive key), gates_scope_required (403 — the key lacks Gates API access), org_not_found (404), nothing_to_change (400), action_not_found (404), not_migrated (503), internal (500). Each action carries kind (action, recovery or signin), signin_qr and, for a Recovery Action, pending_where_url / pending_where_url_at. Recovery and Sign-on Actions are placed in the Console, not here.

data
object
required