revoke grant
# Revoke a Challenge Grant
Withdraws a grant before its lifetime runs out — the operator who issued one from your own panel changed
their mind, or the incident it was issued for turned out not to be one.
Reporting `FAILED` also withdraws a grant, but that records an outcome: the person was put through a
challenge and did not pass it. Use this operation when nothing of the sort happened and you simply want the
bypass gone.
## Endpoint
```
POST {base_url}/api/v1/{account_id}/projects/{project_id}/challenges/grant-revocations
```
## Authentication
Requires API key authentication:
```
Authorization: Bearer {api_key}
```
## Path Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Yes | Your unique BotBye account identifier |
| `project_id` | string | Yes | The project the grant was issued for |
## Request Body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `subject` | object | Yes | Whose grant to withdraw |
| `subject.visitorId` | string | No | The BotBye visitor id the grant was issued on, up to 256 characters |
| `subject.userAccountId` | string | No | Your own account id for the end user, up to 256 characters |
At least one of `subject.visitorId` and `subject.userAccountId` is required. Both are withdrawn when both are
given: a grant issued by a backend that knew only the account is held on the account, and one issued from a
validation event is held on the visitor.
`subject.customFields` has no effect here. Custom fields narrow which requests a grant releases; they do not
identify the grant, and a revocation that matched them would leave it standing whenever your copy of them had
drifted from what was stored.
## Response Structure
| Field | Type | Description |
| --- | --- | --- |
| `revoked` | boolean | Whether anything was standing on the identity. `false` is not a failure: a grant expires or runs out of attempts on its own, and by then there is nothing left to withdraw |
## Use Cases
- **Issued by mistake**: an agent granted the wrong user, or granted for longer than they meant to.
- **Incident closed early**: the account turned out to be compromised after all.
> **Accepted permissions**
> `Project → Challenges → Action → Revoke challenge grant`
>
> **Token scope**
> `Project Action`
Authentication
X-Api-Keystring
Personal access token. Create it in your BotBye account under **Profile → Personal Access Tokens**, tick the scopes the endpoints you call require (see each endpoint's **Token scope**), and send the token in the `X-Api-Key` request header. A token works only for the account it was created in.
Path parameters
account_id
project_id
Request
This endpoint expects an object.
subject
Response
success
reportId
grantExpiresAt
grantRemainingAttempts
Errors
400
Bad Request Error