YATTA
DocsCompare
Protocols

WebFinger

Let other servers find your users. One URL, one small JSON answer.

WebFinger answers one question: “who is this account?” Other servers — for example fediverse software — ask Yatta at /.well-known/webfinger and get a small JSON document back with the user’s profile link.

Look up a user

The lookup key is the full address, not just the name before the @. Only users who exist in Yatta’s auth store get an answer.

Look up a userts
curl "http://localhost:4000/.well-known/webfinger?resource=acct:ada@example.com" # Answer — Content-Type: application/jrd+json{  "subject": "acct:ada@example.com",  "links": [    {      "rel": "http://webfinger.net/rel/profile-page",      "type": "text/html",      "href": "http://localhost:4000"    },    {      "rel": "self",      "type": "application/jrd+json",      "href": "http://localhost:4000/.well-known/webfinger?resource=acct:ada@example.com"    }  ]}

Filter links

Add ?rel=... to keep only links with that relation. You can repeat it for more than one.

Only the self linkts
curl "http://localhost:4000/.well-known/webfinger?resource=acct:ada@example.com&rel=self" # Answer — only the matching link survives{  "subject": "acct:ada@example.com",  "links": [    {      "rel": "self",      "type": "application/jrd+json",      "href": "http://localhost:4000/.well-known/webfinger?resource=acct:ada@example.com"    }  ]}

Errors

400
No ?resource= parameter.
404
Unknown account, or a resource that is not an acct: address.

Where the answer comes from

The profile link points at the app itself. Its base URL comes from the APP_URL environment variable, or http://localhost:4000 when that is not set.

Warning
WebFinger reveals which email addresses have an account: 200 means yes, 404 means no. That is how a discovery protocol works — only expose it publicly if that is fine for your app.