Alias window

These changes shipped with BotShield 3.0 on September 28, 2026. Production accepts both the old and the new names until the window closes.

BotShield 3.0 renames several parameters, attributes and events. Your existing integration keeps working. For a fixed period, the alias window, BotShield accepts both the old name and the new name. An alias is an old name that still works and means the same as its replacement.

Date	What happens
3.0 release	New names are available. Old names keep working, and a response to a request that used an old name says so.
15 October 2026	The published start of the alias window.
15 January 2027	The sunset. Old names stop working.

You reached this page from the Link header of a response if your integration still sends an old name. Find the name in the tables below and replace it before the sunset.

What changes

API parameters

Old name	New name	Where
`scope`	`gate`	Request field or query parameter on `POST /sdk/create-verification-link`, `GET /sdk/partner-config` and `POST /sdk/revoke-verification`
`enroll`	`notarize`	Request field on `POST /sdk/create-verification-link`
`link_on_verify`	None	Request field on `POST /sdk/create-verification-link`. It is accepted and has no effect. See Removed behavior.

The value does not change. gate takes the same gate Key that you sent as scope.

Old name	New name	Notes
`enroll`	`notarize`	Same behavior as `notarize`. Neither attribute can turn the offer on while the gate’s switch is off. The widget logs one console warning when it sees `enroll`.
`link-on-verify`	None	Accepted, no effect. The widget logs one console warning.

The widget attribute scope does not change. Keep scope="your-gate-key" on <botshield-verify>. Only the API parameter is renamed.

Old name	New name
`botshield:census-status`	`botshield:gate-status`
`botshield:multipass-status`	`botshield:gate-status`

During the window the widget fires all three events with the same detail. If you listen to more than one of them, your handler runs more than once per click. Listen to botshield:gate-status only.

Gate status values

Responses that list gates use these status values. Requests that filter by status accept the old values during the window.

Old value	New value
`pending`, `pending_revisions`	`draft`
`approved`	`active`
`denied`, `cancelled`	`archived`

During the window each row carries the new value in status and the old value in status_legacy.

Webhook event types

Webhook event types were renamed before the window and are not aliased. BotShield sends only the new types.

Old type	New type
`census.human_verified`	`gate.human_verified`
`census.unavailable`	`gate.unavailable`
`q.card.proposed`	`agents_ask.card.proposed`
`q.resolution.confirmed`	`agents_ask.resolution.confirmed`
`q.resolution.denied`	`agents_ask.resolution.denied`
`q.resolution.expired`	`agents_ask.resolution.expired`

An endpoint that is subscribed to an old event type receives nothing, and no error is reported. Open the endpoint in the Console under Settings, Developer Tools, Webhooks, and subscribe it to the new types. See Webhook events.

What dual-served means

During the window every renamed name is dual-served: accepted in both forms on the way in, and returned in both forms on the way out.

Direction	Behavior
Requests	You can send the old name or the new name. When you send both, the new name is used.
Responses	A response that carries a renamed field carries both. For example, `create-verification-link` returns `gate` and `scope` with the same value.

You can move one call at a time. There is no switch to flip and no version to select.

How you are told

When a request uses an old name and not its replacement, the response says so in two places.

Response headers

Deprecation: true
Sunset: Sat, 15 Jan 2027 00:00:00 GMT
Link: <https://docs.botshield.ai/changelog/alias-window>; rel="deprecation"

Response body

The response envelope gains a _deprecation object beside the result.

{
  "data": {
    "data": {
      "request_id": "req_4b1f0c6e2a9d4e7f8a3b5c6d7e8f9a0b",
      "gate": "checkout",
      "scope": "checkout"
    },
    "_deprecation": {
      "used": ["scope → gate"],
      "sunset": "2027-01-15T00:00:00Z",
      "link": "https://docs.botshield.ai/changelog/alias-window"
    }
  }
}

Field	Description
`used`	Each old name the request used, with its replacement.
`sunset`	When the old names stop working.
`link`	This page.

A request that uses only new names gets neither the headers nor _deprecation. Log either signal in your integration to find the calls you still have to change.

After the sunset

From 15 January 2027:

A request that sends only an old name is refused. The error code is alias_retired, and the message names the replacement.
Responses no longer carry the old fields, such as scope and status_legacy.
The widget no longer fires botshield:census-status or botshield:multipass-status, and it ignores enroll.
The deprecation headers and _deprecation are no longer sent.

{
  "data": {
    "error": {
      "code": "alias_retired",
      "message": "`scope` was retired on 2027-01-15; send `gate`. https://docs.botshield.ai/changelog/alias-window"
    }
  }
}

Removed behavior

link-on-verify on the widget and link_on_verify in the API used to make a successful gate pass remember that your user reference belongs to the human who passed. In 3.0 a gate pass no longer records anything about an account.

Before 3.0	From 3.0
A gate pass with a user reference linked that reference to the human.	A gate pass never creates or changes a binding.
`link-on-verify="false"` opted out.	The attribute is accepted and has no effect.

To bind an account to a human, offer Trusted Accounts. The person confirms the binding with a passkey.

Checklist

Search your code for scope in BotShield API calls and send gate. Leave the widget attribute scope as it is.
Remove enroll. The gate’s Notarize account with BotShield switch in the Console turns the offer on. Use notarize="false" only to hide the offer on one placement.
Remove link-on-verify and link_on_verify.
Listen to botshield:gate-status and remove listeners for the two old event names.
Read status and stop reading status_legacy.
Check that your webhook endpoints are subscribed to the current event types.
Confirm that your responses no longer carry the Deprecation header.

Get Started

BotShield Gate

Trusted Accounts

Agents Ask

Webhooks

Console

Server SDK

Integrations

Concepts

Changelog

What changes

API parameters

Widget attributes

Widget events

Gate status values

Webhook event types

What dual-served means

How you are told

Response headers

Response body

After the sunset

Removed behavior

Checklist

​What changes

​API parameters

​Widget attributes

​Widget events

​Gate status values

​Webhook event types

​What dual-served means

​How you are told

​Response headers

​Response body

​After the sunset

​Removed behavior

​Checklist

What changes

API parameters

Widget attributes

Widget events

Gate status values

Webhook event types

What dual-served means

How you are told

Response headers

Response body

After the sunset

Removed behavior

Checklist