What is a bot identity?
To verify AI agent identity, you need two answers about a request: which bot sent it, and how strongly that claim was proven. A bot identity carries both. In Arcjet, it's one record on the bot rule's reason that names the bot, says what kind of client it is, and gives an evidence level that runs from UNVERIFIED to SIGNATURE.
When Arcjet Cloud detects a bot, it reports one primary identity with the following fields:
| Field | What it tells you |
|---|---|
kind |
|
botId | The bot's ID, such as |
evidence | How Arcjet established the identity: |
operator | The hostname that signed the request, such as |
spoofed |
|
delegated |
|
You read the identity on each rule result: result.reason.identity in JavaScript, result.reason_v2.identity in Python, and result.Reason.Bot.Identity in Go. In Python, the bot ID field is bot_id. In Go, field names start with a capital letter, such as BotID.
Only Arcjet Cloud computes the identity. A decision that the SDK makes locally, such as a denial from its local bot detection, has no identity.
For more information about the fields, see Bot identity in the Arcjet docs.
Why does the evidence level matter?
A bot name without an evidence level can't carry a policy decision, because the cheapest way to claim a name is to type it. Any client can send ChatGPT-User or Googlebot in its User-Agent header. The evidence level tells you whether anything other than the client confirmed the name.
Consider a rule that gives AI agents a higher rate limit than anonymous visitors. If the rule reads only the bot name, every scraper that copies ChatGPT-User's User-Agent string gets the higher limit. If the rule also requires IP or SIGNATURE evidence, the scraper has to send its requests from OpenAI's network or sign them with OpenAI's private key.
The evidence level also separates two questions that bot management used to answer together. Classification asks what the client says it is. Verification asks whether that's true. A route that only logs AI traffic can act on classification. A route that grants access needs verification.
How strong is each kind of evidence?
The four evidence levels form a ladder. SIGNATURE proves control of a private key that the operator publishes. IP proves that the request left the operator's network. FINGERPRINT proves that a program drives the browser but not who runs it. UNVERIFIED is only what the client claims.
| Evidence | What produces it | What it proves | How an attacker defeats it | Policy it supports |
|---|---|---|---|---|
SIGNATURE | A Web Bot Auth signature, or a Personal Agent Protocol session, that verifies against keys the operator publishes on its own domain | The holder of the operator's private key signed the request | Steal the private key, replay a signature that covers only
| Named access on read paths, per-operator rate limits, and delegated access combined with your own authorization |
IP | The operator's published address ranges, Arcjet's IP data naming the address as the crawler's, or forward-confirmed reverse DNS | The request left the operator's network | Send traffic from inside the operator's network, or exploit an application that trusts a client-supplied IP header | Crawler allow lists and agent access to public content |
FINGERPRINT | Advanced signals browser checks that failed | A program drives the browser | Patch the automation markers that the checks look for. The level doesn't name an operator to impersonate | Deny forms and rate limit, without granting named access |
UNVERIFIED | A | What the client chose to send | Write the string | Classification, logging, and a low-trust budget |
Signature evidence
SIGNATURE evidence comes from one of two protocols. Web Bot Auth signs each HTTP request with RFC 9421 HTTP Message Signatures, using a key from a directory at /.well-known/http-message-signatures-directory on the operator's domain. The Personal Agent Protocol sends a Poppy-Session token, signed by a short-lived key that the agent's published keys authorize.
Arcjet verifies the signers in the open well-known-bots catalog by bot ID, and any other Web Bot Auth signer that you name with a SIGNED_BOT: entry. Only SIGNATURE evidence sets operator, because only a signature ties the request to a domain.
A signature identifies the operator, not the end user. Browserbase, Kernel, and Cloudflare Browser Run sign for many customers, so a valid signature from one of them tells you which platform sent the request, not which customer's agent or what it intends. For more information, see hosted browser agent signatures.
IP evidence
IP evidence means that the source address belongs to the operator. Arcjet gets it from the operator's published ranges, from its own IP data when that data names the address as the crawler's, or from forward-confirmed reverse DNS: the address resolves to a hostname under the operator's domain, and that hostname resolves back to the same address. Google documents both methods for its crawlers.
IP evidence is only as reliable as the client address that your application resolves. If your application runs behind a proxy or load balancer, configure trusted proxies, or a client can set the address that Arcjet checks.
Fingerprint evidence
FINGERPRINT evidence comes from advanced signals, which run checks in the browser and report automation. An identity with this evidence has kind AUTOMATION and no bot ID. It tells you that a program controls the browser, which is enough to deny a signup form, but it can't tell you whether that program belongs to a person's assistant or a scraper.
Unverified evidence
UNVERIFIED evidence means that Arcjet matched the bot by its User-Agent header or by IP reputation and couldn't confirm it. Some bots can't be verified at all. Coding agents such as Claude Code fetch pages from the developer's own computer, so no operator address range applies, and Arcjet reports them with UNVERIFIED evidence without marking them as spoofed.
What does spoofed mean?
spoofed means that Arcjet checked a bot's claim against the operator's addresses and the claim failed. A request that claims to be Googlebot from an address that Google doesn't publish, and that doesn't reverse-resolve to a Google hostname, is spoofed. A spoofed identity always has UNVERIFIED evidence.
spoofed and UNVERIFIED evidence differ in what you know. UNVERIFIED alone means that nobody confirmed the claim: the operator may publish no ranges, or Arcjet may have no data for the address. spoofed means that the claim was tested and is false. That's evidence of intent, because a client that copies a crawler's name is trying to get what the crawler gets.
Arcjet's AI agent helpers return false for a spoofed identity: isAiAgent in JavaScript, is_ai_agent in Python, and decision.IsAIAgent() in Go. The isSpoofedBot helper in @arcjet/inspect, is_spoofed_bot in Python, and decision.IsSpoofedBot() in Go report the bot rule's spoofed result, which also works on routes where you only read the rule's conclusion.
For more information about how impersonation works and how to respond to it, see detect bot spoofing.
What does delegated add?
delegated means that an AI agent presented a verified Personal Agent Protocol session, so it acts for one of its users who delegated access to it. It's set only with SIGNATURE evidence, and operator is then the agent's domain. Meta's Muse, which Arcjet reports as META_MUSE, is an example.
A delegated identity proves more than a signature alone: a signature names the agent, and the session adds that a person stands behind this request. It doesn't identify that person. The user ID in the session is pseudonymous and different for each business, according to the Personal Agent Protocol specification. The session also doesn't prove that the person approved this specific action.
Arcjet verifies sessions only for agents that are vetted in the well-known-bots catalog, and it doesn't fetch a client_id URL that a request supplies. It checks the session against the request's method and URL. Your authorization server checks the access token and its scopes. A session that fails verification, or comes from an agent that isn't in the catalog, doesn't change the identity.
Which identity does Arcjet report when several bots match?
When a request matches several bots, Arcjet reports the one with the strongest evidence. If two matches have equally strong evidence, Arcjet prefers an AI agent, then an AI crawler, then other bots, then automation.
This rule decides cases that would otherwise look contradictory. Suppose a script runs in a Browserbase session and sets its User-Agent header to Claude-User. The Browserbase signature verifies, so BROWSERBASE has SIGNATURE evidence. The Claude-User claim comes from a Browserbase address, not one of Anthropic's, so it's spoofed or, at best, UNVERIFIED. The identity is BROWSERBASE, because a verified signature outranks an unconfirmed name.
The identity is a summary, not the whole decision. Your detectBot rule still applies to every bot the request matched. If a request carries a verified signature and also matches a bot that your rule denies, the decision stays denied.
How do you write policy by evidence level?
Write the policy in your request handler as a function of the identity: deny spoofed claims, give delegated agents what your authorization server permits, give verified agents read access, and keep unverified claims to public pages. The handler already knows the route, the user, and the business operation, so it can decide what a verified agent may do there.
The following examples allow search engines and AI agents, then map the identity to a tier. Account routes accept people and delegated agents, and your authorization server still checks the token. The catalog API accepts agents with IP or SIGNATURE evidence.
Write policy by evidence in JavaScript
import arcjet, { detectBot, type ArcjetBotIdentity, type ArcjetDecision,} from "@arcjet/node";import http from "node:http";
const aj = arcjet({ key: process.env.ARCJET_KEY!, rules: [ detectBot({ mode: "LIVE", allow: ["CATEGORY:SEARCH_ENGINE", "CATEGORY:AI_AGENT"], }), ],});
// Evidence levels, from weakest to strongestconst STRENGTH = { UNVERIFIED: 0, FINGERPRINT: 1, IP: 2, SIGNATURE: 3 };
// Return the primary bot identity from an enforced bot rule, if anyfunction botIdentity(decision: ArcjetDecision): ArcjetBotIdentity | undefined { for (const result of decision.results) { if (result.state !== "DRY_RUN" && result.reason.isBot()) { return result.reason.identity; } } return undefined;}
type Tier = "person" | "bot" | "delegated" | "verified" | "claimed" | "deny";
function tierFor(identity: ArcjetBotIdentity | undefined): Tier { if (!identity) return "person"; if (identity.spoofed || identity.kind === "AUTOMATION") return "deny"; if (identity.kind !== "AI_AGENT") return "bot"; if (identity.delegated) return "delegated"; if (STRENGTH[identity.evidence] >= STRENGTH.IP) return "verified"; return "claimed";}
const server = http.createServer(async (req, res) => { const decision = await aj.protect(req); const tier = tierFor(botIdentity(decision));
if (decision.isDenied() || tier === "deny") { res.writeHead(403).end("Forbidden"); return; }
// People and delegated agents. Your authorization server checks the token. const account = req.url?.startsWith("/account"); if (account && tier !== "person" && tier !== "delegated") { res.writeHead(401).end("Sign in to manage an account"); return; }
// The catalog API needs IP or SIGNATURE evidence from an agent if (req.url?.startsWith("/api/catalog") && tier === "claimed") { res.writeHead(403).end("Unverified agent"); return; }
res.writeHead(200).end("OK");});
server.listen(3000);Write policy by evidence in Python
This FastAPI app has one bot rule, in LIVE mode, so the helper reads the first bot result:
import os
from arcjet import BotCategory, BotIdentity, Decision, Mode, arcjet, detect_botfrom fastapi import FastAPI, Requestfrom fastapi.responses import JSONResponse
app = FastAPI()
aj = arcjet( key=os.environ["ARCJET_KEY"], rules=[ detect_bot( mode=Mode.LIVE, allow=[BotCategory.SEARCH_ENGINE, BotCategory.AI_AGENT], ), ],)
# Evidence levels, from weakest to strongestSTRENGTH = {"UNVERIFIED": 0, "FINGERPRINT": 1, "IP": 2, "SIGNATURE": 3}
def bot_identity(decision: Decision) -> BotIdentity | None: """Return the primary bot identity from the bot rule, if any.""" for result in decision.results: reason = result.reason_v2 if reason.type == "BOT": return reason.identity return None
def tier_for(identity: BotIdentity | None) -> str: if identity is None: return "person" if identity.spoofed or identity.kind == "AUTOMATION": return "deny" if identity.kind != "AI_AGENT": return "bot" if identity.delegated: return "delegated" if STRENGTH[identity.evidence] >= STRENGTH["IP"]: return "verified" return "claimed"
@app.get("/api/catalog")async def catalog(request: Request): decision = await aj.protect(request) tier = tier_for(bot_identity(decision))
if decision.is_denied() or tier == "deny": return JSONResponse({"error": "Forbidden"}, status_code=403)
# The catalog API needs IP or SIGNATURE evidence from an agent if tier == "claimed": return JSONResponse({"error": "Unverified agent"}, status_code=403)
return {"products": []}
@app.post("/account")async def account(request: Request): decision = await aj.protect(request) tier = tier_for(bot_identity(decision))
if decision.is_denied() or tier == "deny": return JSONResponse({"error": "Forbidden"}, status_code=403)
# People and delegated agents. Your authorization server checks the token. if tier not in ("person", "delegated"): return JSONResponse({"error": "Sign in"}, status_code=401)
return {"message": "Account updated"}Write policy by evidence in Go
package main
import ( "log" "net/http" "os" "strings"
"github.com/arcjet/arcjet-go")
// Evidence levels, from weakest to strongestvar strength = map[arcjet.BotEvidence]int{ arcjet.BotEvidenceUnverified: 0, arcjet.BotEvidenceFingerprint: 1, arcjet.BotEvidenceIP: 2, arcjet.BotEvidenceSignature: 3,}
// botIdentity returns the primary bot identity from an enforced bot rule.func botIdentity(decision arcjet.Decision) *arcjet.BotIdentity { for _, result := range decision.Results { if result.State == arcjet.RuleStateDryRun || result.Reason.Bot == nil { continue } return result.Reason.Bot.Identity } return nil}
func tierFor(id *arcjet.BotIdentity) string { switch { case id == nil: return "person" case id.Spoofed || id.Kind == arcjet.BotKindAutomation: return "deny" case id.Kind != arcjet.BotKindAIAgent: return "bot" case id.Delegated: return "delegated" case strength[id.Evidence] >= strength[arcjet.BotEvidenceIP]: return "verified" default: return "claimed" }}
func main() { aj, err := arcjet.NewClient(arcjet.Config{ Key: os.Getenv("ARCJET_KEY"), Rules: []arcjet.Rule{ arcjet.DetectBot(arcjet.BotOptions{ Mode: arcjet.ModeLive, Allow: []string{ arcjet.BotCategorySearchEngine, arcjet.BotCategoryAIAgent, }, }), }, }) if err != nil { log.Fatal(err) }
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { decision, err := aj.Protect(r.Context(), r) if err != nil { http.Error(w, "Internal Server Error", http.StatusInternalServerError) return } tier := tierFor(botIdentity(decision))
if decision.IsDenied() || tier == "deny" { http.Error(w, "Forbidden", http.StatusForbidden) return }
// People and delegated agents. Your authorization server checks the token. if strings.HasPrefix(r.URL.Path, "/account") && tier != "person" && tier != "delegated" { http.Error(w, "Sign in to manage an account", http.StatusUnauthorized) return }
// The catalog API needs IP or SIGNATURE evidence from an agent if strings.HasPrefix(r.URL.Path, "/api/catalog") && tier == "claimed" { http.Error(w, "Unverified agent", http.StatusForbidden) return }
w.Write([]byte("OK")) })
log.Fatal(http.ListenAndServe(":3000", nil))}A decision without an identity, such as one that the SDK made locally, falls into the person tier, so keep your usual checks for people there. The tiers are a starting point, not a standard. A docs site might accept claimed coding agents everywhere, and a store might send verified agents to its API rather than its HTML. For more information about applying tiers to allow and deny decisions, see how to block AI crawlers but allow AI agents.
What doesn't an evidence level tell you?
An evidence level tells you how strongly Arcjet established who sent a request. It doesn't tell you whether to allow the request, who the end user is, or what they intend. Those decisions stay in your code.
The following limits apply at every level:
SIGNATUREnames an operator, not a person. A hosted browser platform's signature covers every customer on that platform.delegateddoesn't identify the user or approve the action. Authorize purchases, password changes, and data deletion with your own checks, and ask a person to confirm irreversible actions.IPdepends on your proxy configuration. A misconfigured trusted proxy lets a client choose its address.- Agents in a person's own browser have no identity. Claude in Chrome and Perplexity Comet send that person's requests, and no level applies to them unless advanced signals detect automation.
For more information about the layers that produce each level, see bot detection techniques and Bot verification in the Arcjet docs.
Frequently asked questions
Is IP verification enough for AI agents?
For fetchers whose operators publish address ranges, such as ChatGPT-User and Claude-User, IP evidence shows that the request left the operator's network. It can't identify a cloud browser on shared infrastructure, and it depends on your application resolving the client address correctly behind proxies.
Can a signature be forged?
Not without the operator's private key. A signature can be replayed, though: one that covers only @authority works until it expires. A hosted browser platform also signs for all of its customers, so a valid signature names the platform, not the customer's agent.
Why does Arcjet report Claude Code as unverified?
Claude Code and other coding agents fetch pages from the developer's own computer, so no operator address range applies. Arcjet reports them with UNVERIFIED evidence and doesn't mark them as spoofed.
What's the difference between spoofed and unverified?
UNVERIFIED means nobody confirmed the claim. spoofed means Arcjet checked the claim against the operator's addresses and it failed. A spoofed identity always has UNVERIFIED evidence, and the AI agent helpers return false for it.
Does a signature identify the end user?
No. A Web Bot Auth signature identifies the operator of the signing key directory. A Personal Agent Protocol session adds that the agent acts for one of its users, but the user ID is pseudonymous and different for each site, and it doesn't prove that the user approved the action.
Which identity does Arcjet report when a request matches several bots?
The one with the strongest evidence. On a tie, Arcjet prefers an AI agent, then an AI crawler, then other bots, then automation. Your detectBot rule still applies to every bot that the request matched.
Application security in your code
Protect your application with Arcjet
Read the bot identity's evidence level in the request handler, where the route and the user decide what a verified agent may do.