Web Bot Auth
Web Bot Auth is an authentication method that leverages cryptographic signatures in HTTP messages to verify that a request comes from an authorized AI Agent. It relies on two active IETF drafts: a directory draft ↗ allowing the agent to share their public keys, and a protocol draft ↗ defining how these keys should be used to attach agent’s identity to HTTP requests. This documentation goes over specific integration within Fingerprint.Generate a valid signing key
You need to generate a signing key which will be used to authenticate your agent’s requests. Generate a unique Ed25519 ↗ private key to sign your requests. This example uses the OpenSSL ↗genpkey command:
jwker ↗ command line application.
JSON web key (jwk) file example
JSON web key (jwk) file example
kid attribute
Now you need to generate the base64 URL-encoded JWK thumbprint ↗ from the public key.
JWK thumbprint code example and result
JWK thumbprint code example and result
kid attribute required for Web Bot Auth, now it’s time to host it publicly.
Host a key directory
You need to host a key directory which creates a way for your agent to authenticate its requests to Fingerprint. This directory should follow the definition from the active IETF draft draft-meunier-http-message-signatures-directory-05 ↗.Host a key directory
Host a key directory at
https://ai-agent.fyi/.well-known/http-message-signatures-directory (note that the full path is a requirement). This key directory should serve a JSON Web Key Set (JWKS) with the public key derived from your private signing key.Serve the directoory over HTTPS
This URL should serve a standard JWKSBesides
x, crv, kid, and kty, you can include other standard JSON Web Key parameters. Multiple Ed25519 keys are supported. Only those for which you provide a signature in the above format are going to be used. Fingerprint will ignore all other key types and key parameters except those containing kty, crv, kid, and xcreated above.Hosted JWKS example
Hosted JWKS example
Register Your Agent
You can submit a request to register your agent using this form in the Fingerprint Dashboard: Submit Your Bot. After submitting all the required information, please wait 1-2 weeks for the agent registration. You’ll get a confirmation email when we have successfully registered your agent.Sign Your Requests
After a successful agent registration, start signing the requests. The signature protocol is defined in draft-meunier-web-bot-auth-architecture-05 ↗. Fundamentally, signing the requests means adding three mandatory HTTP signature headers to each request that your agent makes:Signature, Signature-Input, and Signature-Agent.
Choose a set of components to sign
A component is either an HTTP header, or any derived components ↗ in the HTTP Message Signatures specification. Fingerprint recommends the following: Choose at least the@authority and signature-agent components. You can optionally add more, such as HTTP method or another HTTP header. The @authority represents the host you are sending requests to. The signature-agent is the root URI of the agent’s public key directory.
Consider this example:
| Name | Value |
|---|---|
| AI agent public key directory | https://ai-agent.fyi/.well-known/http-message-signatures-directory |
signature-agent component | "https://ai-agent.fyi" |
| AI agent making requests to | https://example.com/blog/2029-12-31-introduction |
@authority component | "example.com" |
Use components with only ASCII values.Fingerprint currently does not support
bs or sf parameter designed to serialize non-ASCII values into ASCII equivalents.Construct the required headers
Construct the three required headers for Web Bot Auth.Signature-Agent header
Construct a Signature-Agent header ↗ that points to your key directory root URI. Note that Fingerprint will fail to verify a message if:
- The message includes a
Signature-Agentheader that is not anhttps:// - The
Signature-Agentis not a bare domain (paths, query params are not allowed) - The message includes a valid URI but does not enclose it in double quotes. This is due to
Signature-Agentbeing a structured field ↗ - The message includes a structured field label (e.g. sig1=“https://ai-agent.fyi”), as labeling is not supported.
Signature-Input header
Construct a Signature-Input header ↗ over your chosen components. The header must meet the following requirements.
| Required component parameter | Requirement |
|---|---|
tag | web-bot-auth |
keyid | This should be equal to the kid value of the public key(notice the difference in naming, keyid vs kid) |
alg | ed25519 |
created | This should be equal to a Unix timestamp associated with when the message was sent by your agent |
expires | This should be equal to a Unix timestamp associated with when Fingerprint should no longer attempt to verify the message. A short expires reduces the likelihood of replay attacks, and Fingerprint recommends using a one hour duration |
nonce | Strongly recommended: a random value that must not be reused, at least 16 bytes, base64 encoded |
Signature header
Construct a Signature header ↗ over your chosen components by signing them with your private key and converting to base64.
JavaScript example of header generation
JavaScript example of header generation
Add the headers to your agent’s requests
Attach these three headers to your agent’s requests. Note that all requests need to be signed, including requests that make fetch requests or download static resources. One option to attach custom headers to all requests is by using Page.route ↗ functionality of Playwright. An example request header collection may look like this:All requests, made by your agent, must be signed, including static resource (images, javascript) and Fetch requests. If using Playwright to add custom headers is not an option, an alternative way to do it is via a browser extension.
bot-registration@fingerprint.com
Helpful Links
Next Steps
Test your Web Bot Auth implementation ↗
Using Fingerprint’s Web Bot Auth Verifier (WBAV) app to test if your agent adheres to the standard
Submit your agent to Fingerprint directory
Subimt your agent or bot to the Fingerprint Bot Directory