Skip to main content


This service implements the WebFinger protocol, which allows remote services to discover local users.


  • Automatically find ActivityPub actors through their username
  • Returns a 404 error if the actor doesn't exist



$ npm install @semapps/webfinger --save


const { WebfingerService } = require('@semapps/webfinger');
module.exports = {
mixins: [WebfingerService],
settings: {
baseUrl: "",
domainName: "" // Not necessary if it is the same as usersContainer


baseUrlStringBase URL of the server. Used to find the domain name if it is not set.
domainNameStringDomain name used for the user@domain webfinger identifier. If not set, the domain name will be guessed from the users' container.

Discovering an user with Webfinger#

In the Webfinger protocol, users are identified by their username and the domain name where they are hosted: username@domain. This is similar to email addresses, except services like Mastodon add a @ at the beginning.

To find an user, a simple GET is enough:

GET /.well-known/webfinger?resource=acct:simon@localhost HTTP/1.1
Host: localhost:3000
Accept: application/json

If the user exists locally, it will return a JSON like this:

"subject": "acct:simon@localhost",
"aliases": [
"links": [
"rel": "self",
"type": "application/activity+json",
"href": "http://localhost:3000/actors/simon"

Additional resources about the protocol#