Documentation

Verifying your identity

Your Subter identity can carry verified claims— proof that the same person controls a GitHub, a domain, an email, and more. Subter checks each proof and co-signs it; your app publishes it; anyone who resolves you sees it. Here’s how to add them.

How verification works

You prove, Subter co-signs

You demonstrate control of an account or domain. Subter verifies it and signs a small statement about it. Your app embeds that statement in the identity document it publishes.

You choose what’s public

Nothing is inferred or auto-published. Each claim is opt-in, added one at a time, and removable by re-publishing without it. Your keys never leave your device.

It’s “directory-attested”

A verified badge means Subter checked the link — a useful signal, but its own trust tier. The strongest check is still comparing a fingerprint out of band.

Two ways to verify

Connected accounts

GitHub, Google, X, email. Connect the account to your Subter account, then sync in the app. Subter reads what was already verified and signs the claim — no extra steps. Sync offers a claim for every connected account and verified email; you choose which to publish — so your other email addresses stay private unless you decide to show them.

Domain

Any domain you control. Publish a one-time token in a DNS record or a file on the site. Covered in detail below.

Coming soon

Bluesky, Nostr, and crypto wallets follow the same start-then-prove flow as a domain and are on the way.

Verify a domain

You prove control by publishing a token Subter gives you, in either a DNS record or a file on the site. Either one is enough — pick whichever you can edit.

Step 1 — Start it in the app

Choose “Verify a domain”, enter the domain (e.g. example.com), and Subter returns a one-time token and the exact string to publish:

subter-verify=<fingerprint>:<token>

<fingerprint>is your identity’s fingerprint and <token> is the value from step 1 — the app fills both in for you. The token is valid for one hour.

Step 2 — Publish the token

Option A — DNS TXT record (recommended). In your DNS provider, add:

Type	`TXT`
Name / Host	`_subter`
Value	`subter-verify=<fingerprint>:<token>`

Most providers append your domain automatically, so the Name is just _subter and the full record becomes _subter.example.com. If your provider asks for a fully-qualified name, enter _subter.example.com. Leave the TTL at its default. DNS can take a few minutes (occasionally longer) to propagate.

Option B — a file on your site. Serve the same string as the entire body of:

https://example.com/.well-known/subter-challenge

The response must be exactly the subter-verify=… string (a trailing newline is fine) over https.

Step 3 — Confirm & publish

The app checks periodically. Once the record is live, Subter verifies control, signs the domain claim, and the app publishes your updated identity — the verified domain now shows on your profile and in /doc, and it verifies offline. You can remove the DNS record or file afterward; re-verify about once a year.

The flow at a glance

Start a domain verification in the app → get a token.
Publish subter-verify=<fingerprint>:<token> as a _subter TXT record (or the .well-known file).
Confirm — the app polls; Subter verifies and signs the claim.
Publish your identity — the verified domain is now public and offline-verifiable.

Troubleshooting

It still says “pending”.

Give DNS a few minutes to propagate. Then check the string is exact — no extra spaces, the right fingerprint and token, and the host is _subter (not the bare domain). Tokens expire after an hour; if yours lapsed, start again for a fresh one.

DNS or the file — which should I use?

Whichever you can edit. DNS TXT is best if you manage the domain’s DNS; the .well-known file is handy if you can deploy to the site but not its DNS. Either alone verifies.

Do I have to keep the record forever?

No. Once the claim is signed and published it stands on its own. You can remove the record, though leaving it makes re-verification (about yearly) a no-op.

Does a verified domain prove who someone is?

It proves control of that domain at verification time, attested by Subter — not an out-of-band identity check. To be certain who you’re talking to, compare fingerprints through a channel you already trust.

Building an integration? See the API reference for POST /v1/claims/start and GET /v1/claims/status/:id, or head back to Help & FAQ.