How to read a PLC directory history
What the PLC directory is, the fields of a did:plc operation (rotation keys, verification methods, aliases, services, prev, sig), nullification and tombstones.
What the PLC directory is
did:plc is the DID method that almost every Bluesky account uses. Its registry, the PLC directory (plc.directory), is a public service that keeps, for each identity, the signed list of every change ever made to it. Anyone can read it: the current document at GET /{did}, the full log at GET /{did}/log/audit.
curl https://plc.directory/did:plc:z72i7hdynmk6r22z27h6tvur/log/auditThe answer is a list of entries, oldest first. Each entry wraps one signed operation with what the directory adds: cid (the operation's content hash), nullified and createdAt (when the directory received it).
The fields of an operation
A plc_operation holds the whole state of the identity, not only what changed: to find the change, compare it with the operation before it, as the viewer does.
| Field | What it holds |
|---|---|
rotationKeys | The keys allowed to sign the next operation, the first one with the highest priority. Usually your server's key, sometimes your own recovery key. |
verificationMethods | The keys of the account itself; atproto is the signing key that signs your posts and records. |
alsoKnownAs | The aliases: the first at:// entry is the handle. |
services | Where the account lives: atproto_pds is its server (PDS); a labeler adds atproto_labeler. |
prev | The CID of the operation this one replaces, null for the first one. |
sig | The signature of the operation by one of the previous rotationKeys. |
{
"type": "plc_operation",
"rotationKeys": ["did:key:zQ3sh…"],
"verificationMethods": { "atproto": "did:key:zQ3sh…" },
"alsoKnownAs": ["at://alice.example.com"],
"services": {
"atproto_pds": {
"type": "AtprotoPersonalDataServer",
"endpoint": "https://pds.example.com"
}
},
"prev": "bafyrei…",
"sig": "…"
}The oldest identities started with a legacy create operation of 2022, with signingKey, recoveryKey, handle and service fields. The viewer reads it the way the reference implementation does: the signing key becomes the atproto method, [recoveryKey, signingKey] the rotation keys, the handle an at:// alias and the service the atproto_pds.
Nullification and recovery
The rotation keys are ordered by priority. For 72 hours after an operation, a key with a higher priority than the one that signed it can sign another operation with the same prev: the directory then marks the first one nullified: true and the identity follows the new one. This is how a recovery key takes an identity back after an unwanted change.
A nullified operation stays in the log, so the viewer keeps it in the timeline with a "Nullified" badge, and compares the operations after it with the last valid one.
Tombstones
A plc_tombstone deactivates the identity in the registry: it has no state, only prev and sig. Like any operation, it can be nullified within 72 hours by a rotation key with a higher priority than the one that signed it, which brings the identity back. Once that window has passed, the DID no longer resolves to a document and no operation can follow. The viewer shows the identity as "Deactivated", and a nullified tombstone with its "Nullified" badge.
How a migration reads
When an account moves to another server, its new server takes over the identity in one operation, signed by the old server's rotation key:
services.atproto_pds.endpointchanges to the new server;verificationMethods.atprotochanges to the new server's signing key;rotationKeyschanges, the old server's key replaced by the new one's.
So a server move with new rotation keys within a day is what a migration looks like, and also what an account takeover looks like: the viewer adds a note when it sees one. If you did not move your account, contact the host of your server. To give a bot a recognisable handle without moving it, see Get your handle.