.png)
3 hours ago
1
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 [email protected].
The service looks up my avatar using a well-known path. For example, request https://shkspr.mobi/.well-known/avatar?resource=acct:[email protected] and you'll get back this JSON:
JSON{
"subject": "acct:[email protected]",
"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.
@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.
What about a size parameter?
@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
Will anyone actually use it?
@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.
What about hashing the email?
@Edent would using a hash of the email address in its place improve privacy? 🤔
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.456ZPersonally, I think that's a bit complicated, but I'm happy to be convinced.
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?
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.
