Skip to navigation
BotBye APIChallenges

revoke grant

View as Markdown

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

ParameterTypeRequiredDescription
account_idstringYesYour unique BotBye account identifier
project_idstringYesThe project the grant was issued for

Request Body

FieldTypeRequiredDescription
subjectobjectYesWhose grant to withdraw
subject.visitorIdstringNoThe BotBye visitor id the grant was issued on, up to 256 characters
subject.userAccountIdstringNoYour 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

FieldTypeDescription
revokedbooleanWhether 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_idstringRequired
project_idstringRequired

Request

This endpoint expects an object.
subjectobjectRequired

Response

success
reportIdstringformat: "uuid"
grantExpiresAtstringOptional
grantRemainingAttemptsintegerOptional

Errors

400
Bad Request Error