Centinel AnalyticaPassports
Issue a credential that lets one tool or partner through your bot protection, verified on every request.
Overview
A passport is a credential you issue to one tool or partner so their requests get through your bot protection.
Use it when you cannot allow that traffic by IP or user agent: the addresses change, or the user agent is one anyone can copy. A passport is checked on every request instead, so you know the traffic is theirs.
Passports are yours alone. No other organisation sees them, and you do not wait on us to add anything.
If the traffic is a public crawler we already track, use the crawler catalog instead. That is one toggle and no credential to exchange.
You manage passports on the Passports page, under Configuration in the sidebar.
Verification methods
A passport verifies one of two ways. You choose when you issue it, and the choice is fixed for that passport's life.
We generate a secret. The holder sends it in an X-Passport-Key header on every request:
curl https://example.com/api/prices \
-H "X-Passport-Key: cbp_abcdefghijklmnopqrstuvwxyz"Choose this when the other side has no signing setup. All it asks of them is the ability to set a header.
It does ask something of you: the header has to survive your edge. Every integration we ship forwards it. Most forward whatever the client sent; the Apache module reads a fixed list of header names, so it has to be a build from this release or newer.
A static key is a bearer secret
Whoever holds the key is the passport. We store it so you can read it back, which also means anyone who can manage your passports can read it. If it leaks, revoke the passport and issue a new one.
The other side signs each request under RFC 9421 and publishes the public half of their signing key at a key directory host: a domain they control, serving a JSON document at a fixed path.
https://partner.example.com/.well-known/http-message-signatures-directoryYou enter only the host. We build the rest of that URL, fetch the document on our own schedule, and check each signature against the Ed25519 keys it lists:
{
"keys": [
{ "kty": "OKP", "crv": "Ed25519", "x": "<base64url public key>" }
]
}No secret is exchanged, and keys are rotated by editing that document.
Name a host the other side controls
Whoever controls that hostname decides which keys we trust for this passport. We check the value is a hostname — not an address, a port or a URL — and nothing more.
Issue a passport
Name the holder
Name the tool or partner that holds the passport, not the person who asked for it. The name is what you match against when you come back to revoke it.
Choose the method and an expiry
Pick Static key or Web bot auth, and for web bot auth enter the key directory host. Then choose a lifetime, or Never. An expiry is what eventually forces someone to look at the credential again, so prefer a date you are willing to revisit.
Send the key
The key is shown with a curl command carrying it, so you can check the passport works before you hand it over. Send it over a channel you trust. You can read it again later from the Show key action on its row.
What a passport changes
A verified request is allowed, and it beats crawler denial. If you have denied a catalogued crawler and then issue a passport to a partner whose fetcher sends that crawler's user agent, the passport wins. If that is not what you want, revoke the passport rather than changing the crawler setting.
Your own rules still run, and they are read before the passport is. A passport turns off the bot verdict, not your policy, so you can hold a holder to certain paths, or block one passport during an incident without revoking it. Use the passport field in a rule.
A rule that only rate-limits does not apply here. The passport allows the request outright, and that answer ends the check before any limit is counted, the same way an allowed crawler does. Policy can narrow a passport or block it, not meter it.
Review and revoke
The Passports page lists every live passport with the requests it admitted in the last day. Open one to see the last seven days in detail: how many requests, from which addresses, and which endpoints they asked for.
The addresses are the part worth checking. A passport goes to one holder, so a credential answering from addresses you do not recognise is the clearest sign a key has leaked.
Revoking is immediate on your side and takes up to a minute to reach every server checking requests. To rotate instead, issue the second passport and send the new key before revoking the old one, so nobody is locked out mid-rotation.