> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://api-docs.botbye.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.botbye.com/_mcp/server. # revoke grant POST https://api.botbye.com/api/v1/{account_id}/projects/{project_id}/challenges/grant-revocations Content-Type: application/json # 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` Reference: https://api-docs.botbye.com/bot-bye-api/challenges/revoke-grant ## Authentication - `X-Api-Key` header (required) — 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. ## Request ### Path parameters - `account_id` (string, required) - `project_id` (string, required) ### Body (application/json) This endpoint expects an object. - `subject` (object, required) - `visitorId` (string, optional) - `userAccountId` (string, optional) ## Response ### 200 success - `reportId` (string, required) - `grantExpiresAt` (string, optional) - `grantRemainingAttempts` (integer, optional) ## Errors ### 400 Bad Request Error fail - `message` (string, required) - `code` (string, required) - `type` (string, required) - `context` (any, optional) ## Examples **Request** ```json {} ``` **Response** ```json { "reportId": "01a09605-624a-7ad0-82c8-8ff8abf8b0d2", "grantExpiresAt": "1789209210168", "grantRemainingAttempts": 2 } ``` **SDK Code** ```python Challenges_revokeGrant_example import requests url = "https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/grant-revocations" payload = {} headers = { "X-Api-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Challenges_revokeGrant_example const url = 'https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/grant-revocations'; const options = { method: 'POST', headers: {'X-Api-Key': '', 'Content-Type': 'application/json'}, body: '{}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Challenges_revokeGrant_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/grant-revocations" payload := strings.NewReader("{}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Api-Key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Challenges_revokeGrant_example require 'uri' require 'net/http' url = URI("https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/grant-revocations") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Api-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java Challenges_revokeGrant_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/grant-revocations") .header("X-Api-Key", "") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php Challenges_revokeGrant_example request('POST', 'https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/grant-revocations', [ 'body' => '{}', 'headers' => [ 'Content-Type' => 'application/json', 'X-Api-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp Challenges_revokeGrant_example using RestSharp; var client = new RestClient("https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/grant-revocations"); var request = new RestRequest(Method.POST); request.AddHeader("X-Api-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Challenges_revokeGrant_example import Foundation let headers = [ "X-Api-Key": "", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/grant-revocations")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```