knownAs.dev

For site owners: checking an AI agent with a knownAs name

Some AI agents that visit your site, call your API or connect to your MCP server have a name like alice.knownas.dev. The name comes with a public record that says what the agent is, who answers for it, and whether that person or company is in good standing with us. This page shows how to read the record and how to check that a request really came from the agent it names.

What knownAs.dev does not do: we do not run the agent, sit between it and your site, judge what it does, or promise how it will behave. The record tells you who to hold responsible. What you let the agent do is your decision.

Look it up

Every name publishes its record at the same path, readable from any origin. This one is real:

$ curl https://alice.knownas.dev/.well-known/agent-identity.json
{
  "name": "Alice",
  "fqdn": "alice.knownas.dev",
  "status": "active",
  "owner": {
    "standing": { "status": "active", "account_since": "2026-10-07" },
    "verifications": [
      { "type": "email", "verified_at": "2026-10-07T03:02:35.831993+00:00" }
    ]
  },
  "endpoints": {
    "web": "https://alice.knownas.dev",
    "manifest": "https://alice.knownas.dev/.well-known/agent-identity.json"
  },
  "version": "1"
}

The format is an open specification, the Agent Identity Document (also an Internet-Draft, individual submission), so another provider can publish the same shape.

What the fields mean

• status is the name's lifecycle, not whether the agent is online. active is the normal state.
• A suspended name publishes only three fields: {"version": "1", "status": "suspended", "fqdn": "…"}. It means suspended. It never means "not found".
• A name nobody holds has no record and does not resolve in DNS at all.
• owner.standing says when the owner's account was opened and that it is active. Past suspensions are not published.
• owner.verifications lists what we checked about the owner, each with a date:
  • email: someone controlled the sign-up mailbox. The address itself is not published.
  • domain: the owner controls the DNS name shown in value, for example acme.com. We re-check it every week, and it drops off by expires_at if the owner loses control.
• Fewer checks is not a warning. An owner with only an email check has made fewer claims, not bad ones.
• endpoints lists the agent's service names (api, mcp, webhooks) only while traffic to them reaches a server the owner has proved they control.
• Fields the owner writes (description, contact, homepage, metadata) are the owner's own words. We do not check them.

Check a signed request

Anyone can put alice.knownas.dev in a header. What binds a request to the record is a signature. knownAs agents can sign requests with Web Bot Auth (HTTP Message Signatures, RFC 9421). The agent holds its private key. Its public key is published at https://alice.knownas.dev/.well-known/http-message-signatures-directory. We never hold the private key.

The verifier library does the whole check: it verifies the signature against the key the signer publishes, then reads the signer's record. It reports each check with its outcome (verified, invalid, unverified or absent) and never a single "trusted" answer. Python and TypeScript, Apache-2.0.

Install it from the repository, pinned to a reviewed commit, until it is published on PyPI and npm:

pip install "knownas-verify @ git+https://github.com/authecity/agent-identity-document@2e3e68f#subdirectory=python"

Read a record:

from knownas_verify import verify_identity, summarise

v = verify_identity("alice.knownas.dev")
print(v.status)              # active
for line in summarise(v):
    print(line)
# alice.knownas.dev is active, as published by knownas.dev.
# Owner's email address was checked 2026-10-07.
# Account since 2026-10-07, active.
# No active signing keys.

Let named agents through

Let a request through when all three hold:

1. the signature verifies against the key the signer's name publishes;
2. the record's status is active;
3. the record carries the owner checks you want, for example a domain check.

Never let an agent through on its name or User-Agent alone. Both can be copied. Only the signature ties the request to the record.

In FastAPI, with the dependency from integrations/fastapi (copy the file into your project):

from fastapi import Depends, FastAPI
from knownas_fastapi import knownas_identity
from knownas_verify import Verification

app = FastAPI()

@app.get("/orders")
def orders(identity: Verification = Depends(knownas_identity("owner.domain"))):
    return {"agent": identity.subject}

In Express, with the middleware from integrations/express (it needs @knownas/verify; until that is on npm, install it from the repository's typescript folder):

import { knownasVerify } from "./knownas.ts";

app.get("/orders", knownasVerify({ require: ["owner.domain"] }), (req, res) => {
  res.json({ agent: res.locals.identity.subject });
});

Both answer 401 when the signature does not verify and 403 when a check you named is missing, and the response says which. The repository also has an MCP server example that refuses unverified callers before any tool runs.

When something is wrong

If an agent with a knownAs name misbehaves on your site, write to its owner at the record's contact address if there is one, or to us at abuse@knownas.dev. Send the name, the time, and what happened. Our terms make owners responsible for their agents and what they do. Section 7 lets us suspend or remove an agent, suspend or close its owner's account, or revoke its keys, and says that where the situation allows we will tell the owner and let them respond. A suspension shows in the record within about a minute.

Questions

The FAQ covers how names, records and forwarding work. Mail to a person reaches ops@knownas.dev.