> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Alias window

> Names that change in BotShield 3.0, the period in which both the old and new names work, and what happens when the old names are retired on 15 January 2027.

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

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](#removed-behavior). |

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

### Widget attributes

| 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. |

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

### Widget events

| 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` |

<Warning>
  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](/webhooks/events).
</Warning>

## 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

```http theme={null}
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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/trusted-accounts/overview). The person confirms the binding with a passkey.

## Checklist

1. Search your code for `scope` in BotShield API calls and send `gate`. Leave the widget attribute `scope` as it is.
2. 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.
3. Remove `link-on-verify` and `link_on_verify`.
4. Listen to `botshield:gate-status` and remove listeners for the two old event names.
5. Read `status` and stop reading `status_legacy`.
6. Check that your webhook endpoints are subscribed to the current event types.
7. Confirm that your responses no longer carry the `Deprecation` header.