Overview
BotProt protects systems from unverified automated usage, for example a ticket shop during a high-demand sale. BotProt runs one or more short steps in the visitor's browser. When they finish, BotProt hands your system a signed token as proof.
Why you need the token
The Shop API refuses every reservation and order request that comes without a final BotProt token for that shop. That includes shops without steps the visitor solves: you still run BotProt and need its token. If you build your own shop on the Shop API, BotProt is part of your checkout.
Why it works this way
In a busy sale, bots buy up tickets and add load to the shop. BotProt makes automation expensive. It mixes types of steps and keeps changing the flow, so a script that worked on one visit may fail on the next.
Your page never needs to know which steps run or in what order. It starts BotProt and waits for the token. Steps can be added or changed without you touching your integration.
How it works
- Your page starts BotProt with the shop's GUID as identifier.
- BotProt runs the steps that are set up for the shop, either in an element you provide or in a skin's container, such as a dialog. The visitor solves some of them. Others need no input from the visitor and finish by themselves.
- BotProt resolves with a final token.
- Your page sends the token in the
x-botprot-verificationheader on every reservation and order request. - When the token expires, run BotProt again for a new one. Running it before expiration will return the existing token.
The smallest integration is one call, see Integration.
Token rules
- A token belongs to one customer and one shop. A token meant for another shop is refused.
- Call the Shop API from that customer's browser, with their own token. Don't share a token between customers: the Shop API counts requests, reservations and orders per token.
- A token is valid for about an hour.
- After a successful order, the token can't be used for another order in that shop. The customer needs a new one.
When the Shop API refuses a token, it answers 403 or 429. See
When the token is refused.
Steps
A visitor may see a puzzle, Cloudflare Turnstile or even a waiting room. The set and order differ per identifier and can change at any time. Don't build your page around a specific step.
Steps without visitor input
Some steps need no input from the visitor and finish by themselves. A shop without steps the visitor solves can still have them set up. One example is a safety net: when traffic peaks, it can hold visitors in a waiting room, so the shop isn't overrun. Usually the visitor passes straight through, but BotProt still has to check, which takes a moment, usually well under a second. When no steps are set up at all, the token arrives right away.
Your page can't tell which case applies, and the setup can change at any time. So always run BotProt and wait for the token before the first reservation. BotProt renders steps that finish by themselves like any other, so a skin can appear on your page for a moment. See The element to keep it from flashing by. Steps the visitor solves can be added to the shop later without any change on your side.
Some identifiers also contain a Queue-it waiting room. For those, the visitor must pass through Queue-it. BotProt rejects the visitor if they skipped the queue or their Queue-it token is invalid.
Next
Start with the smallest integration, then pick a skin to make the steps look more integrated.