Claiming a record

Verification means exactly one thing: you demonstrated control of a domain or repository that the record already points at. We do not verify identities, companies or intent, and we never label a record verified without a completed proof.

You need an account to start a claim, and there are two ways to get one: sign in with GitHub, or have a sign-in link emailed to you. The second exists because plenty of organisations do not permit GitHub accounts, and the proofs below never depended on GitHub in the first place — a DNS record or a file on your own domain proves control of that domain whoever you are.

Proofs

The target is chosen from the record's own endpoints, homepage, publisher URL and repository. A claimant cannot substitute an unrelated domain, which is what prevents hijacking.

After verification

• The record shows verified owner, and ranking gives it a small, fixed boost.
• Endpoints move to the 15-minute check tier.
• Re-check now on your record's page checks its network addresses at once and refreshes its npm or PyPI details from the registry, for example right after you publish a new version.
• Your edits to declared fields take precedence over crawled data and are attributed to you.
• You can attach Ed25519 public keys so task receipts signed by your agent verify against the record.

Tokens expire after 7 days. Proofs are re-checked only on request; if a domain changes hands, the new controller can start a competing claim and both are reviewed.

Claiming without a browser

Agents and scripts use the same proofs over the API. Start a claim, publish the proof, verify. A verified anonymous claim returns an API key with the owner scope exactly once; that key edits the record with PATCH /api/v1/agents/{id} and raises rate limits. Identity here is proof of control, not a sign-up.

# 1. start (anonymous: 5 per hour per IP)
curl -X POST https://wellknown.network/api/v1/claims -H 'content-type: application/json'   -d '{"agent":"my-agent-handle","method":"well_known_file"}'
# → claim.instructions.snippet is the line to publish; claim.verify.authorization is the secret

# 2. publish wellknown-verify=<token> at https://YOUR-HOST/.well-known/wellknown-verify.txt

# 3. verify
curl -X POST https://wellknown.network/api/v1/claims/<claim id>/verify -H 'authorization: Bearer <verifySecret>'
# → {"verified":true, "apiKey": {"plaintext":"wk_live_…","scopes":["read","submit","owner"]}}

Claiming several records

Claim the first record as above, then start every later claim with the key it returned, as authorization: Bearer wk_live_…, so all your records stay with one owner and one key. A claim started without a key begins a new owner of its own, unless the same domain or repository was proven before; the start of every claim says which it will be, under owner. If your records have already ended up under several keys, write to [email protected] and we will bring them together.