Every site that I sign up for asks me to upload an avatar to represent myself. Whenever I change my photo, I have to log in to a hundred sites and change it there⁰.

Perhaps they could all use Gravatar - but that's a centralised service¹ and doesn't work with wildcard email addresses. Libravatar also relies on email addresses and requires implementers to set up new DNS entries.

So I'm proposing .well-known/avatar. Here's how it works (for now). I'd like your feedback before going further².

I sign up to a service and use the email address whatever@shkspr.mobi.

The service looks up my avatar using a well-known path. For example, request https://shkspr.mobi/.well-known/avatar?resource=acct:whatever@shkspr.mobi and you'll get back this JSON:

{
    "subject": "acct:whatever@shkspr.mobi",
    "links": [
        {
              "rel": "http:\/\/webfinger.net\/rel\/avatar",
             "type": "image\/webp",
             "href": "https:\/\/shkspr.mobi\/.well-known\/avatar\/avatar-1024.webp",
            "sizes": "1024x1024"
        },
        {
              "rel": "http:\/\/webfinger.net\/rel\/avatar",
             "type": "image\/jpeg",
             "href": "https:\/\/shkspr.mobi\/.well-known\/avatar\/avatar-512.jpg",
            "sizes": "512x512"
        }
    ]
}

That's a slightly enhanced https://webfinger.net/rel/#avatar which adds a sizes parameter. The service can then pick the appropriate MIME and size.

Alternatively, you can request the same URl but with a header of Accept: image/gif and receive the default sized avatar in that specific format.

Try it by running:

curl -H "Accept: image/avif" https://shkspr.mobi/.well-known/avatar/ --output "test.avif"

You should receive an auto-converted version of my avatar.

Some Thoughts

Please add your thoughts to the comments box. Here's some feedback I've received so far.

Perhaps this is too complicated? What's wrong with just serving up an image when the URl is requested? That would make it easier for static sites.

Simon Josefsson

@jas@fosstodon.org

@Edent Thinking about this, while I like content negotiation as a clever hack, I wonder if maybe it isn’t too clever. The nice thing with WKD is that you can deploy it with any normal static HTTP file without any special magic. Maybe the protocol could be dumbed down to simply rely on WKD-style URLs? I’m not sure how to configure my web server (Apache) for your avatar well known URL with negotiation magic.

2025-10-23, 16:50 0 boosts 1 favorites

What about a size parameter?

Chip

@chip@talking.dev

@Edent It'd be nice if the query could limit the size of the avatar being returned. If only there were `Accept-Max-Size`, but maybe a query param? I wouldn't want my performance taking a dive if Alice has a 35M avatar that my client starts downloading. If my client had requested with `max_size=3072` I'd rather not see the avatar than degrade performance/pull excess data

2025-10-23, 15:02 0 boosts 1 favorites

Will anyone actually use it?

Andreas Gohr

@splitbrain@fedi.splitbrain.org

@Edent good luck with getting the hundreds of services to implement it. I mean it. it would be awesome and you might be well connected enough to make it happen.

2025-10-23, 15:03

What about hashing the email?

David Bushell 🎮

@db@social.lol

@Edent would using a hash of the email address in its place improve privacy? 🤔

2025-10-25, 11:52 0 boosts 0 favorites

You've already given the service your email address, and your domain already knows your account name - so there's no privacy leak here. Obviously, a service shouldn't hotlink to your avatar image.

How about DNS?

I like it. Is there an argument that service / endpoint should be specifiable at the DNS level?As others in your comments pointed out, if your site is currently just static, some users might prefer to run an entirely separate dedicated avatar service.

— Emily Shepherd (@emi.ly) 2025-10-25T11:57:43.456Z

Personally, I think that's a bit complicated, but I'm happy to be convinced.

Is this restricted to email?

No! For example, if you know my GitHub username then you should be able to get the avatar from https://github.com/.well-known/avatar?resource=acct:edent

How can a service tell if the avatar has been updated?

Perhaps a hash, timestamp, or something else?

Can requests for multiple accounts be sent at once?

I'm not sure how / if WebFinger handles this. I suppose there ought to be some limit to avoid overwhelming a server.

Proposal

I think the default should be to return an image.

If an accept of image/… is requested, the server should try to return an image in that format.

If an accept of application/json or similar is requested, the server should return a JSON document listing the available avatars.

I don't think a ?size= GET parameter is necessary; services can resize once they've downloaded, or use the JSON document to get the right size.

A limited amount of alt text could be added using the title attribute in the JSON.

Before I start writing up anything formal - I'd love your constructive criticism on this.

When I sign up to a web service, I don't want to faff around uploading an image to use as my avatar. I want that service to look at my email address or social-sign-in and automatically pick up my preferred graphic.

Here's how I see it working.

1. A user signs in to a service with the email address username@example.com
2. In a similar way to WebFinger, the service makes a request to:
   • example.com/.well-known/avatar?resource=acct:username@example.com
3. If the request's Accept header has a MIME type of image/*, then the server immediately returns an image.
4. If the request's Accept header has a MIME type of application/json, then the server can return a WebFinger-style document with "rel":"http://webfinger.net/rel/avatar" and, perhaps, a list of different images, formats, and sizes.

This makes it incredibly simple for people to use the same avatar everywhere.

It also means that if you're designing a service which publicly shows usernames, you can make avatars available without an expensive API call. For example, Twitter could make user's avatars available at: twitter.com/.well-known/avatars?resource=acct:edent

But what about...?

This is a sketch of an idea. I'd like to know if people think it is useful before I take it any further.

I don't think it breaches privacy - a user's image is public on all services anyway.

Users should still be given the option of changing their avatar if they want.

A service shouldn't expose the user's email address - they should proxy the image.

Anything else I should have thought of?

Updates

To stave off some common points raised.

• No this isn't like Gravatar. That works by being a 3rd party service and using the MD5 of your email address.
• No this isn't like Libravatar. See above.
• No this isn't like WebFinger. That only returns JSON.
• No this isn't like h-card. That requires a server to parse HTML in order to find an image.
• No this isn't like BIMI. That's expensive and only supports SVG.