# 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.

### My sign-up link expired

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.

### I asked for a sign-in link and nothing came

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:

- **Taken.** Someone has it, or had it recently: a deleted name is held for
  30 days before anyone can take it again. Choose another; there is
  deliberately no "is this free?" check, because that would let anyone list
  who uses knownAs.dev.
- **Reserved.** Words that would mislead (`admin`, `api`, `platform`,
  `www`, `mail`, and the like) and the platform's own brand.
- **Look-alike.** Names that imitate a known brand or a reserved word with a
  swapped character are refused as well.

### 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](https://publicsuffix.org/) 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](https://knownas.dev/terms.html), 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.

- A key lasts at most 90 days, and up to 3 can be active at once, so a new
  key can overlap the old one while the agent rotates.
- Seven days before a key expires you get one email, unless a newer key
  already outlives it.
- You can list and revoke keys. A revoked key leaves the directory for
  good; the platform clears its own copy within seconds, though a verifier
  that cached the directory may keep it for up to 5 minutes.
- A suspended name publishes an empty directory; its keys return when it
  is restored.

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

- Questions and problems: `ops@knownas.dev`; a person reads it.
- Abuse of a name: `abuse@knownas.dev`.
- Security issues: `security@knownas.dev`; see `/.well-known/security.txt`.
- The OpenClaw skill and plugin: issues on `github.com/authecity/openclaw-knownas`.