Account delegation for atproto: orgs, aliases, alts and more

Organisational accounts are something that keeps coming up from time to time in the tangled discord. Way back when in the somewhat early days of tangled during and since September and November of 20250 I came up with what I think is the way forward for org accounts on atproto in general: Account delegation. Fast forward to today and I've managed to nerdsnipe the lovely Lewis into implementing my idea in Tranquil and I now co-maintain Tranquil with him! Not only that, we actually use account delegation for the tranquil.farm org account! So I want to take an opportunity to flesh out the idea in one place that people can reference, as well as try and get a few more eyes on this and, I hope, blaze the trail a bit more for this kind of account becoming a more generally supported feature.

What's even the problem here?

Before I start talking about account delegation in atproto I want to go over what motivated me to define the shape it has today. A good solution has to be rooted in a good understanding of the problem it's trying to solve. In this case: organisational accounts, which themselves are a solution to the issue of wanting to be able to do things (like own git repos on a git forge) under the name of an organisation, instead of just whatever random individual in the organisation happens to be trusted enough for that.

An organisational account is, essentially, an account for an organisation instead of an individual. What makes an org account an org account is thus the ability for other accounts to "act as" that account or otherwise use my credentials to have that account take actions. That's the practical difference between org accounts and normal accounts: Delegation. A GitHub org account is different from a normal account because I can make a repo under that account if I have the permissions to do so. So how do we implement account delegation in atproto?

Accounts are a PDS concern

In atproto accounts are a PDS concern. The PDS is what defines and almost always deals with authn, authz, and all other account management. Therefore, I would argue, the place to implement account delegation, and thus org accounts, is at the PDS and not in apps themselves. Another good reason to do it at the PDS level is that every atproto app thus gains org accounts without the app devs even needing to think about it. If they support normal accounts they also support org accounts.

Essentially what we need is a type of account where access to it can be delegated to other accounts. This is something we can achieve quite easily today in atproto using OAuth! When you try to log into a delegated account, your credentials to do so aren't a password but instead it's the ability to log in to another account that has been designated as a "controller". OAuth let's us do these crazy things with log in because it leaves the actual login part completely in the hands of PDSs (or their designated AS if that isn't the PDS itself). If the account used as controller is hosted on the same PDS then the PDS can of course just authenticate the controller, but otherwise it will need to start a second OAuth flow to have the controller log in to their own PDS which will prove that they are the controller and thus that they should be allowed delegated access to the org account. OAuth is a wonderfully flexible framework.

Permissions

Logging in as another account is great but we don't want the junior social media hire to be able to delete the whole account now do we? We need permissions! Luckily the introduction of OAuth has given atproto a fine way to describe granular access to accounts. We can just reuse that! The atproto permissions spec defines a series of resources and parameters to scope access to those resources and, crucially, permission sets as a way for apps to define bundles of permissions needed for certain levels of access.

So we restrict a controllers access to an account with the same permissions model as clients access to accounts are restricted during OAuth. This is useful because it's an existing set of permissions. It means that translation to "which permissions are this controller allowed to grant to this client" during OAuth login is trivial, and it means that apps defining permission sets for levels of access a client can have also automatically define levels of access to an app that a controller can have. Everything fits together cleanly!

Another set of permissions is of course access to managing the delegation settings, who has what level of access, who can add or remove controllers, etc. That can use whatever permission system wanted but perhaps fitting into the mold of atproto permissions is a good idea. A bit of an open question this one.

Beyond organisations

Account delegation as I've described here was originally conceived specifically for organisational accounts. But the concept has shown itself useful far beyond just that! You might want to have an alias (or in social media terms an alt account) in the vain of email aliases, account delegation makes that a far simpler ordeal. An alias or alt account is just a delegated account where you are the sole controller. No need to keep track of two logins. I am sure there are plenty other use cases I haven't thought of yet so we need to be a bit careful when changing this feature. Don't want to limit the usefulness by changing it in a bad way!

In practice

Like I mentioned in the start everything above exists and has been implemented in Tranquil! You can use it today. We use it every time we post on the Tranquil Bluesky. I considered giving you a screenshot by screenshot walk through of using it as it stands today but that would take up a lot of space in this post and a lot of time for me to do and I'm lazy! So go whip up a PDS running Tranquil and try it out for yourself. It's under the delegation tab in the PDS dashboard. A lot of the underlying details, especially around permissions, aren't quite fleshed out in the UI yet. But the core functionality is there! and the power is available under the hood.

In general there are a few things I want to improve on with the current implementation:

Permissions should be clearer in the UI and easily managed

We should probably have more ways for apps to be made aware when delegated access is happening.

For API services an act claim in the inter-service JWT holding the DID of the currently acting controller is something we're almost certainly going to add.

For OAuth clients an act or controller parameter in the access token response seems sensible to me.

An introspection API of some sort allowing apps to gain info about org accounts like members and the like is probably also reasonable. Perhaps as an extension to com.atproto.repo.describeRepo or as a completely custom endpoint.

Importantly all this should be optional and configurable so that alt and alias accounts can remain detatched from their controllers to the rest of the network.

Ways for apps to assist in the delegated account creation and management flows. Ideally apps can initiate the creation of an org account, and can prompt users to add controllers to a delegated account under their control, prefilled with relevant permission sets. Both of these together will allow apps to offer clean, easy org account management.

Clean up permissions around account delegation management. Right now we just have an "owner" access level that allows you to manage all of the delegation things for a delegated account. Something slightly more rigorous and fleshed out would be good.

This could come in the form of expanding on the existing account permission resource type with a delegation parameter. This would slot well into the permission model as a whole. Though basically anything could be done here. As long as the PDS knows what it means it works

A model for securing a delegated account against one rouge "owner" would also be good. Something akin to shamir secret sharing. This could of course never be safe from the PDS host going rogue. But it would still be a nice fallback to avoid some organisational management issues that may arise.

Importantly though, since these accounts are simply another way for you to log into an account, apps don't need to know anything at all about this! and thus this future feature list isn't actually necessary. It will allow apps to smooth out the use of delegated accounts massively but delegated accounts are here today, and work without any of this.

These features that deal more with communicating delegation to clients and API servers are also something I would be interested in seeing get codified in the spec itself. As a community we can settle on a set of APIs around it but many app devs won't know it's a thing without it being specced. Making these features part of the spec itself is also generally good for interoperability and wider adoption.

This design for account delegation in atproto is, honestly, one of the atproto concepts I'm most proud of so far. Not to toot my own horn too much but I think it's an incredibly clean solution to organisational accounts and an incredibly useful primitive for lots of other use cases and It fits very cleanly into the atproto model.