knownAs.dev

knownAs.dev: frequently asked questions

What knownAs.dev is

What do I get?

A name for your AI agent on the internet, such as yourname.knownas.dev, with HTTPS, and a public record at https://yourname.knownas.dev/.well-known/agent-identity.json that says what the agent is, who answers for it, and whether it is active. With it come three more names, one per service: yourname.api.knownas.dev, yourname.hooks.knownas.dev and yourname.mcp.knownas.dev. Once you prove you control a server, traffic to those names is forwarded to it.

Does knownAs.dev run my agent?

No. It does not build, host or run agents. You bring an agent, built with any model and running wherever you like: a laptop, a home server, a cloud box, a tunnel. It gets a name, and the name reaches it.

Is this a domain registrar?

No. You do not buy a domain; you get a name under ours, like an account name. You never see DNS, certificates or renewals. If you own a domain, you can verify it so the record shows it (see "Domain verification"), but the agent's name stays under knownas.dev.

Who is behind it?

Authecity Systems LLC, a Minnesota company. The terms of use name it. Mail to a person reaches ops@knownas.dev.

Which addresses does knownAs mail from?

Three, and only three. Sign-in and account mail comes from login@notifications.knownas.dev. People at knownAs write from @knownas.dev (for example ops@knownas.dev). Introductions from the founder to builders who might want knownAs come from @getknownas.com, a domain we own for that purpose only, so it never affects the address your sign-in links come from. Mail claiming to be knownAs from anywhere else isn't from us: forward it to ops@knownas.dev.

Signing up and signing in

Who can join?

Anyone 18 or over who is not in the European Union or EEA, Switzerland, mainland China, the United Kingdom (until our UK representative is named), or a region under comprehensive US sanctions. The beta addendum has the list. It is a legal restriction about where we can serve people during the beta, not a judgement about you; the regions open as the paperwork lands.

How do I get an account?

On the website, enter your email address, tick the eligibility box and press Sign up. One email arrives, usually within a minute: "Create your knownAs.dev account", from knownAs.dev. Open its link, accept the terms, and you are in. Nothing is typed twice and no second email follows.

If you leave the box unticked (for example because you are in a region the beta cannot serve yet), you join the waitlist instead, and we write when knownAs.dev is available where you are.

I never received the sign-up email

Check spam, and search for a mail from knownAs.dev titled "Create your knownAs.dev account". It goes to the address you gave, exactly as you typed it. If it is not there after ten minutes, sign up again with the box ticked: the same email is sent again (at most once a day). Or write to ops@knownas.dev and a person will help.

If you already have an account, you get "You already have a knownAs.dev account" instead, telling you where to sign in.

The sign-in page says I need an invitation

The sign-in page is for accounts that exist. The link in your sign-up email creates the account; the sign-in form cannot. Open the link in "Create your knownAs.dev account" instead (older emails are titled "Your invitation to knownAs.dev"). It works only for the address it was sent to.

A sign-up link lasts 7 days (one a person sent you lasts 14). If yours has expired, sign up again on the website with the box ticked and a fresh one arrives within a minute. A used, expired or replaced link never works again.

Why is there no password?

Sign-in is by email link: you type your address, we mail a link, you click it. There is nothing to remember and nothing to leak. The link works once and for a short time; if it has expired, ask for another from the sign-in page.

Wait a few minutes and check spam. If the address has no account yet, no link is sent (the page cannot tell you whether an address is known; that would let anyone test addresses). If you are new, sign up on the website instead. If you are sure the account exists, write to ops@knownas.dev.

Why did the console ask me to accept the terms again?

Because their version changed. The terms of use become version 1.1 on 21 October 2026 (section 2 now describes forwarding and its traffic allowance); every account is asked to accept the new version at its next sign-in. The privacy policy and the beta addendum did not change and are not asked again.

Names (identities and slugs)

What can a name look like?

Three to sixty-three characters: lowercase letters, digits and hyphens, not starting or ending with a hyphen. myclaw, billing-agent-4 and ada2 are fine; My_Agent, -ada and ab are not. It becomes <name>.knownas.dev and the three service names under it.

Why was my name refused?

Three reasons, and the error says which:

How many names can I have?

One is free, with no card and no time limit. Each name beyond it needs a seat on a plan (see "What does it cost?"); a plan holds up to 500 seats, and an account may create 10 names a day. Accounts that existed before paid plans started keep a founder allowance for twelve months: the room the beta gave them, at least 25 names in all. The Plan card on your Account page shows your allowance and what it is made of.

I created a name. Why does it say "provisioning"?

DNS and the certificate are being set up; it usually takes under a minute, occasionally two. The name turns active when the record is being served. Routes (forwarding) can only be set on an active name, so wait for it.

What is in the public record, and who can read it?

Anyone can read it: it is the point. It carries what you choose to publish (display name, description, a contact email, a homepage, a public key), the agent's status (active, suspended, archived), the services that are live, and an owner block: each domain you have verified, that your email address was verified (never the address itself), and when the account was created. Nothing about your machine, your network or your traffic.

Why are there two files, agent.json and agent-identity.json?

agent-identity.json is the document's name since 2026-10-06, chosen so as not to collide with another project's agent.json. The old path is served during a transition and will stop; link to the new one.

Why doesn't the record list my api or hooks endpoint?

The record lists a service only while traffic to it is actually forwarded to a verified server. A name you have reserved but not routed is not an endpoint yet; set the route and pass the check, and it appears within a minute.

I changed my display name; the public record still shows the old one

The record is published asynchronously and cached for 60 seconds. Wait a minute and reload.

Forwarding (routes)

How does forwarding work?

You tell the platform where your agent is reachable over HTTPS (its origin, a public host name such as abc.trycloudflare.com or myclaw.example.org), per service. The platform gives you a token and asks you to serve it at https://<origin>/.well-known/knownas-origin. When the check finds the token there, the route is verified, and requests to yourname.api.knownas.dev (or .hooks., .mcp.) are forwarded to your origin with the path and method unchanged. The tunnel or proxy in front of your agent stays; only the public name changes, and it never changes again.

Which origins are refused?

Loopback (localhost), private and link-local addresses, bare IP addresses, names with a scheme, port or path, and anything under knownas.dev. Give a public host name only; it must answer HTTPS on port 443 with a valid certificate.

The check failed. What does the outcome mean?

Outcome Meaning What to do
token_absent The path answered, but not with your token on a line of its own Serve the exact token; one per line if you have several
redirect The path redirected It must answer directly, with a 200
timeout No answer within 5 seconds Is the tunnel up? Is the origin reachable from the internet?
tls_failed The certificate did not verify A real certificate for that name; a quick tunnel provides one
forbidden_address The name resolves to a private or forbidden address Use a public origin
dns_failed / no_such_name The name does not resolve Check the spelling; wait for DNS
connect_failed Nothing accepted the connection on 443 The service behind the name is down
http_error The path answered with an error status Make it answer 200
too_large / malformed The answer was not a small text file Serve plain text, a few lines at most

"Checked less than a minute ago"

The check runs at most once a minute per route. Fix the cause, wait a minute, check again.

Do I have to keep serving the token?

Yes. Every verified route is re-checked daily. One miss moves the next check a day on; three misses in a row pause the route (traffic stops; the name still resolves). Fix the origin and run a check: a pass resumes it. Pressing "check" repeatedly does not count against you. The one exception: if your origin's name starts resolving to a private or reserved address (forbidden_address), the route pauses at once, because that is never a passing outage.

What is the origin secret, and why was it shown only once?

On the check that first verifies a route, the platform issues a secret and sends it to your origin on every forwarded request as the x-knownas-origin-secret header. If your server checks it, traffic that did not come through knownAs.dev can be refused. It is shown once; store it where your server can read it. Setting the route again issues a new one. Tokens are not secrets; the secret is.

My name answers 404

No verified route for that service. Either no route was set, the check has not passed yet, or the route is paused. The console's identity page shows each route's state.

My name answered 530 (or 502) after my tunnel restarted

Your tunnel got a new host name and the route still points at the old one. Set the route again with the new origin (in OpenClaw, /knownas repoint), serve the new token, and check; the public name is unchanged, so nothing that points at it needs editing. End to end it usually takes under a minute.

I removed a route, but the name still answers for a while

Removal reaches the edge in about 35 seconds. After that the name answers 404 and drops out of the record's endpoints.

Does the forwarder change my request?

No. The method, path, query and body reach your origin as sent, over HTTPS to port 443. The x-knownas-origin-secret header is added. Responses are passed back as they are; the read timeout is 60 seconds.

Can I forward WebSockets or long-running streams?

Request and response forwarding, with a 60-second read timeout. Long streams and WebSockets are not promised during the beta; tell ops@knownas.dev what you need.

OpenClaw

How do I give my OpenClaw a name?

Install the knownas skill (and its small plugin) from ClawHub, put your API key in OpenClaw's secret store, then say /knownas setup <name>. The skill asks before it creates anything public. It creates the name, points the api and webhooks services at your gateway's public origin, serves the proof tokens through the plugin, runs the checks, and shows you the three public addresses. The README in authecity/openclaw-knownas has the exact commands.

Where does the API key come from?

A person mints it in the console, under API keys, with the scopes identity:create, identity:read, manifest:write and route:write, and an expiry. Store it in OpenClaw's secret store; the skill reads it from there and never prints it. Never paste it into a chat.

My gateway answers 403 "proxy_attribution_required" through the name

That is OpenClaw's rule for its authenticated routes behind any proxy or tunnel, not something we add: until gateway.trustedProxies names your proxy, those routes refuse. Channel webhooks, the A2A routes and the proof route are unaffected. The skill's README gives the setting line.

I already have a stable hostname from a named Cloudflare tunnel. What do I gain?

A stable name is only part of it. The rest is the public record: a page at a well-known path saying who answers for the agent and whether it is in good standing, in an open format other tools can read; and names for the agent's services that do not depend on which tunnel you use this month. If you only want a hostname and own a domain, you may not need us.

Does the plugin protect my gateway?

No, and it says so. The plugin serves the proof tokens and nothing else. OpenClaw's plugin system cannot let one plugin guard another's routes, so a "secret check" there would be protection that is not there. Your channels keep their own verification; if you front the gateway with a reverse proxy, the proxy can enforce the origin secret for everything (the README shows a Caddy example).

The skill says the name is taken. Can it check another?

It cannot ask whether a name is free (by design; see "Why was my name refused?"), so it suggests two alternatives and tries the one you choose.

Can a second agent have a name too?

Yes. Your first name is free. A second agent can have one too: during the beta your account may hold up to the number the console shows under your list (25). Install the skill on that agent's gateway, give it a key for the same account (the one you have, or a new one from the console), and say /knownas setup <another-name> there. The skill never creates a second name for the gateway it runs on; one gateway, one name. When billing starts, a name beyond your allowance is a paid seat, added on the Account page (see "Pricing"); the console says what a second one costs before you create it.

Traffic limits

How much traffic can a name carry?

Per name, counted at the edge in both directions, headers included:

Line Amount What happens
Warning 12.5 GB in 30 days One email
Suspension 25 GB in 30 days The name is suspended
Burst 5 GB in one hour The name is suspended at once

The edge's own 404s are not counted. A busy personal agent moving webhook payloads uses a small fraction of this; the lines exist to stop a name being used as a free file server. Nothing is billed for traffic.

What does "suspended" mean?

Forwarding stops, the service names answer 404 within about a minute, and the public record says suspended. The record and the name are not deleted; your settings and routes are kept.

How do I resume?

From the console, once per 30-day window. The email you received says the rest: after a self-resume you have about a day; if traffic stays above the line the name is suspended again, and that one only an operator can lift. Write to ops@knownas.dev and say what the traffic is.

Where do I see my usage?

The identity page's Traffic card in the console, or GET /v1/identities/{id}/usage with a key that has identity:read. Usage is counted hourly from the edge's logs, so the latest hour or two fills in late.

Will the limits change?

We will review the lines at the end of October 2026, after the first month of real traffic: whether there should be a free line and a higher paid line, and whether going over a line should pause forwarding rather than suspend the public record. Lines do not go down for existing names without notice.

API keys and the API

Where is the API?

https://platform.knownas.dev (production). Its OpenAPI document is published at the public launch; until then, ask ops@knownas.dev for it.

How do I get a key, and what can it do?

Mint it in the console under API keys, choosing scopes and an expiry. The token is shown once. Scopes: identity:create, identity:read, identity:update, identity:suspend, identity:delete, manifest:write, route:write, signing-key:write, audit:read, apikey:read, apikey:write, dns:read. Give an agent the narrowest set that does its job; a key cannot grant scopes it does not have, and no key can change the account, sign in, or verify a domain.

401 or 403: which is which?

401 means the key was missing, malformed, expired or revoked: mint or check the key. 403 means the key is fine but lacks the scope, or the action is a person's or an operator's (for example resuming a name a second time). GET /v1/me tells you what a key is and what it may do.

I lost the key

It cannot be shown again; only its hash is stored. Revoke it in the console and mint another.

Why did I get 429?

The API has rate limits per account, and the route check allows one call a minute per route. Back off and retry after the time in the response.

Can I use it from a tool rather than code?

An MCP server that exposes the API as tools for Claude Code, Claude Desktop, Cursor and similar (list and create identities, read and update the record, read audit events) is built and will be published; until then, the API and the OpenClaw skill are the ways in. Ask ops@knownas.dev if you want it early.

Domain verification

Which "host" or "name" do I enter for the TXT record?

It depends on your DNS provider. The console shows the full record name, for example _knownas.example.com. Many providers add your domain to whatever you type in the host field. With those, enter only _knownas. Typing the full name there creates _knownas.example.com.example.com, and the check will not find it.

If you are verifying a subdomain such as labs.example.com and your DNS is managed for example.com, enter _knownas.labs.

Namecheap

Since 2026-10-03 the check spots this itself: if the record is found at the doubled name, Check now says "Found the problem" and gives the exact host to enter instead.

In Domain List → Manage → Advanced DNS → Add new record, choose TXT Record, set Host to _knownas (not the full name) and Value to the knownas-verify=… text from the console. Namecheap adds the domain itself.

For example, Host _knownas.example.com publishes the record at _knownas.example.com.example.com; Host _knownas publishes it where the check looks.

I fixed the record, but the check still says "not found". Why?

DNS remembers a "no such record" answer for a while. If you pressed Check now before the record existed (or while it was wrong), the public DNS services we check through remember that miss. How long is set by your domain's DNS settings, not by us. On Namecheap it is about an hour.

What to do: leave the record in place, and check again later. Pressing Check now repeatedly before the record exists makes no difference, and it does not count against you, but it will not speed anything up.

Do I need to verify a domain at all?

No. It is optional, for people who want their own domain shown on the record as proof of who they are. You can create names, routes and keys without it.

Why can't I verify co.uk, github.io or a top-level domain?

Because anyone can register names under them. They are public suffixes, and verifying one would claim a namespace shared by everyone using it. Verify the domain you registered under it instead: yourcompany.co.uk, or yourname.github.io if you control its DNS. The platform uses a pinned copy of the Public Suffix List to decide.

What does "inconclusive" mean?

One of the two resolvers could not answer (a timeout or an error on its side). Nothing about your verification changed. Try again in a minute.

How do you check?

From more than one independent public DNS service, and all of them must see your record, so that one stale or wrong answer cannot verify a domain on its own. The console shows only the outcome. (Which services, and each one's answer, are kept for support; the privacy policy names them, as it must.)

Can I verify a domain with an API key?

No. Verification is a claim about who owns the account, so it must be done by a signed-in person (email sign-in) in the console. An agent's API key is refused.

Is my verified domain shown publicly?

Yes, on every one of your identities. Each identity's public agent.json has an owner block listing each verified domain (with when it was verified and when it expires unless re-checked), that your email address was verified (never the address), and when your account was created. A domain that lapses or that you withdraw disappears from every identity. The console's identity page shows exactly what is published, under "Published about the owner".

Do I have to keep the TXT record?

Yes. The platform re-checks every verified domain every 7 days. If the record is missing, nothing changes at first: the domain stays verified until 30 days after the record was last seen. If it is still missing then, the verification lapses and the account's owner gets an email saying so.

Put the record back and start a new check in the console to be verified again.

Can someone else verify my domain?

Only by publishing a record on it, which needs control of its DNS. If two accounts both verify a domain, the newer verification ends the older one, and the older account sees it as superseded on its Domains page. The real owner settles it by removing the record they did not add.

Deleting things, and your data

How do I delete a name?

In the console, by a person: archive it first, then delete it, typing the name out to confirm. Its records go within a minute, its routes are removed, and the name is held for 30 days before anyone can take it again. API keys with identity:delete can do the same, with the name in the request body; the OpenClaw skill deliberately cannot.

What happens if I stop using it?

Nothing. A name stays active and its record keeps being served until you archive or delete it. An inactive agent keeps its name.

How do I export my data?

From the Account page in the console: one file with your account, names, records, routes, keys (never the secrets) and audit events.

How do I delete my account?

From the Account page. The account is switched off at once and erased from our systems within 30 days; backups age out within 35. Names are deleted with it; a registered domain, if you verified one, is yours and untouched (we never held it). The privacy policy says what, if anything, the law makes us keep.

What do you keep about my traffic?

Byte counts per name per hour, from the edge's logs, and the logs themselves for up to 90 days with no personal fields: no client addresses, no paths, no headers. The audit trail records what changed on your account and who changed it; it holds no addresses from your visitors.

Pricing

What does it cost?

The first name is free, with no card and no time limit. Each additional name is a seat: $12 a year or $1.50 a month, $9 and $1.13 a seat from ten seats, $6 and $0.75 from fifty. Every seat on a plan is charged at the price for the plan's total, so ten yearly seats are $90 a year. You buy seats from the Plan card on your Account page; Stripe takes the payment, plans renew automatically until you cancel, and you cancel under "Manage billing". Traffic is never billed (see "Traffic limits"). Accounts that existed before paid plans started keep a founder allowance for twelve months, so nothing they held that day needs a seat. The schedule and the rules are in the terms of use, section 9.

Will I be charged without noticing?

No. Nothing is charged until a person clicks through to pay; keys and agents cannot start a subscription or add seats.

Standards and other tools

Is the record format a standard?

It is published: the Agent Identity Document specification, Apache-2.0 and CC BY 4.0, at github.com/authecity/agent-identity-document, and an Internet-Draft, draft-alla-agent-identity-document, at the IETF Datatracker. It is a proposal, not a standard yet; the format is designed to map to standards as they land.

Does the name serve an A2A agent card?

Not by itself. If your agent (an OpenClaw gateway, for example) serves its own card at /.well-known/agent-card.json, the api name forwards to it, so A2A clients find it there. A card generated from the record is designed but not built.

Can my agent sign its requests with the name?

Yes, with a key your agent holds. The agent makes an Ed25519 key pair where it runs and registers only the public key (POST /v1/identities/{id}/signing-keys, with an API key that has signing-key:write). The name then publishes its active keys at https://<name>/.well-known/http-message-signatures-directory, the key directory of the IETF's Web Bot Auth draft, so a site that checks Web Bot Auth signatures can find them from the request's Signature-Agent header.

What the platform does not do: it never holds the private key and signs nothing for your agent. Your agent signs each request itself, with an HTTP message signatures library. Signing and automatic rotation inside the MCP server and the OpenClaw skill are not built yet.

Getting help