Skip to navigation
BotBye APIChallenges

report

View as Markdown

Tells BotBye how a challenge one of your users was given was answered — by your own MFA, by a captcha you run yourself, by ours solved out of band, or by a person in your support team.

A PASSED report may carry a grant, which makes the next requests of that user answer ALLOW where they would have answered CHALLENGE. A grant never lifts a BLOCK: a request we consider malicious is declined whatever a report said.

A FAILED report withdraws any grant standing on either identity it names, and may not carry one.

Endpoint

POST {base_url}/api/v1/{account_id}/projects/{project_id}/challenges/reports

Authentication

Requires API key authentication:

Authorization: Bearer {api_key}

Path Parameters

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

Request Body

FieldTypeRequiredDescription
subjectobjectYesWho the report is about
subject.visitorIdstringNoThe BotBye visitor id the challenged request carried, up to 256 characters
subject.userAccountIdstringNoYour own account id for the end user, up to 256 characters
subject.customFieldsobjectNoUp to 5 of your own key/value pairs the granted requests must also carry
resultstringYesPASSED or FAILED
channelstringYesWhat verified the person: CAPTCHA, MFA, EXTERNAL_CAPTCHA or MANUAL
grantobjectNoPresent to buy a bypass; omit to file the report alone
grant.ttlSecondsintegerYes, within grantHow long the bypass lives, 60–86400
grant.maxAttemptsintegerNo, within grantHow many requests it releases, at least 1; omit to release every request until the bypass expires
requestIdstring (uuid)NoThe request_id your evaluate call returned for the request the challenge was put in front of

At least one of subject.visitorId and subject.userAccountId is required: a grant is keyed on one of them, and customFields can only narrow that key. A grant keyed on a custom field alone would be claimable by anyone who guessed the value, since custom fields arrive with every request.

subject.visitorId is only usable on requests that carry a BotBye token, which is where the visitor id can be verified. A report about a backend-only flow should name subject.userAccountId instead.

requestId matters only on a PASSED report over MFA: BotBye then records the device that made that request as verified for the end user’s account. On any other report it is stored with the report and changes nothing. The request must belong to the identity the report names — when it was made under another subject.userAccountId or subject.visitorId, the report answers 400 challenge_report.challenged_request_of_another_subject, with the mismatching field in context.field.

Response Structure

FieldTypeDescription
reportIdstringIdentifier of the report; also the id of the grant it issued
grantExpiresAtstringTimestamp (epoch millis) the grant stops applying; absent when the report issued none
grantRemainingAttemptsintegerRequests the grant still releases; absent when the report issued none, and when the grant it issued counts no attempts

Use Cases

  • Support: a user cannot pass the captcha and contacts you; report the identity check your agent performed and let their next few requests through.
  • Your own MFA: report a passed multi-factor check so the user is not challenged again straight after it.
  • Third-party captcha: report the result of a captcha you run yourself.

Accepted permissions Project → Challenges → Action → Report challenge result

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
resultenumRequired
Allowed values:
channelenumRequired
Allowed values:
grantobjectOptional
requestIdstringOptionalformat: "uuid"

The request_id the evaluate call returned for the challenged request. Used on a PASSED MFA report to record that request’s device as verified for the account.

Response

success
reportIdstringformat: "uuid"
grantExpiresAtstringOptional
grantRemainingAttemptsintegerOptional

Errors

400
Bad Request Error