Terence Eden. He has a beard and is smiling.
Theme Switcher:

Alpha launch - .well-known/avatar - feedback wanted

· 12 comments · 750 words · Viewed ~1,259 times

I've gotten sufficiently annoyed with a trivial problem that I'm preparing to write an IETF RFC. Yeah. That's how ticked off I am!

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 there0.

Perhaps they could all use Gravatar - but that's a centralised service1 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 further2.

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:

 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:

 Bashcurl -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

@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

@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

@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 🎮

@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.

  1. OK, I don't have to. But I want to. I dislike having last year's photo cluttering some half-remembered social network. ↩︎

  2. We live in the redecentralised future now! ↩︎

  3. I wrote about this in 2004 and in 2020. It takes me time, but I get there eventually! ↩︎

Share this post on…

12 thoughts on “Alpha launch - .well-known/avatar - feedback wanted”

  1. I've no problem with webfinger type resources, but I would point out that assuming responses vary based on "Accept:" headers makes it less efficient to use with a proxying cache server.

    Proxying CDNs (such as CloudFront) don't apply the logic directly (they can't without being provided specific additional configuration) so just treat the header (which from browsers is usually a list of types rather than a specific type) as a key. Which means supporting "Accept:" headers means requesting the same backend resource for every different change in that header.

    So a "MAY" rather than a "SHOULD".

    Reply

  2. @Edent This feels like it's conflating two problems: Distributed identity, and publication of a point of contact for an avatar service. I'd suggest focusing on content of the avatar service and stick to a user-supplied URI for a locator.

    A directory service to find the avatars is really a directory service for finding identity records.

    Reply | Reply to original comment on a2mi.social

  3. @Edent Big fan of the decentralization goal! Also curious about what can be learned from Gravatar (what to do, or what not to do). Since quite a few sites do use them, I wonder if having some compatibility with their "API" could be beneficial, to reduce implementation friction. (Edit: also curious about what drove their choice to use hashes)

    I also wonder about how the standard would handle "wild success" - if Gmail or Yahoo wanted to implement it, how would that shift the requirements (including non-functional requirements like security)?

    Great idea, good for you for tackling the general case!

    Reply | Reply to original comment on infosec.exchange

  7. @Edent Would it be better to use the path rather than the query string, maybe (so .well-known/avatar/cjwatson@debian.org rather than .well-known/avatar?resource=acct:cjwatson@debian.org)? Seems like it'd be a bit easier for static hosting folks to deal with, and it should be no harder for people who can deploy a web service.

    Reply | Reply to original comment on mastodon.ie

  8. Re: How can a service tell if the avatar has been updated?

    I think this is already solved by cache headers.

    Reply

  10. As a static site author, I would want to implement this by just putting some files in a .well-known folder on my server. But the behaviour regarding Accept headers would prevent this AFAICS.

    Reply

What are your reckons?

All comments are moderated and may not be published immediately. Your email address will not be published.

See allowed HTML elements: <a href="" title="">
<abbr title="">
<acronym title="">
<b>
<blockquote cite="">
<br>
<cite>
<code>
<del datetime="">
<em>
<i>
<img src="" alt="" title="" srcset="">
<p>
<pre>
<q cite="">
<s>
<strike>
<strong>

To respond on your own website, write a post which contains a link to this post - then enter the URl of your page here. Learn more about WebMentions.