Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bluesky-social/atproto/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The com.atproto.identity namespace provides lexicons for resolving and managing decentralized identifiers (DIDs) and handles in the AT Protocol.

​
Key Concepts

  • DID: Decentralized Identifier (e.g., did:plc:z72i7hdynmk6r22z27h6tvur)
  • Handle: Human-readable identifier (e.g., alice.bsky.social)
  • DID Document: JSON document containing identity information and service endpoints
  • PLC Operations: Operations for managing DID:PLC identities

​
Queries

​
resolveHandle

Resolves an atproto handle to a DID. Endpoint: com.atproto.identity.resolveHandle
​
handle
string
required
The handle to resolve (e.g., alice.bsky.social)
Response:
​
did
string
required
The resolved DID for the handle
Example: 
const response = await agent.com.atproto.identity.resolveHandle({
  handle: 'alice.bsky.social'
})

console.log(response.data.did)
// Output: did:plc:z72i7hdynmk6r22z27h6tvur

curl "https://bsky.social/xrpc/com.atproto.identity.resolveHandle?handle=alice.bsky.social"
Errors:
  • HandleNotFound: The handle does not resolve to any DID

​
resolveDid

Resolves a DID to its DID document. Endpoint: com.atproto.identity.resolveDid
​
did
string
required
The DID to resolve (e.g., did:plc:z72i7hdynmk6r22z27h6tvur)
Response: Returns the complete DID document as JSON. Example: 
const response = await agent.com.atproto.identity.resolveDid({
  did: 'did:plc:z72i7hdynmk6r22z27h6tvur'
})

console.log(response.data)

​
resolveIdentity

Resolves a handle or DID to complete identity information, including validated handle and DID document. Endpoint: com.atproto.identity.resolveIdentity
​
identifier
string
required
Handle or DID to resolve
Response:
​
did
string
required
The resolved DID
​
handle
string
required
The validated handle, or handle.invalid if handle does not match DID document
​
didDoc
object
required
The complete DID document for the identity
Example: 
const response = await agent.com.atproto.identity.resolveIdentity({
  identifier: 'alice.bsky.social'
})

console.log(response.data.did, response.data.handle)

​
getRecommendedDidCredentials

Get recommended PLC credentials for creating a new DID. Endpoint: com.atproto.identity.getRecommendedDidCredentials No parameters required. Response: Returns recommended signing and rotation keys for creating a new DID.

​
Procedures

​
updateHandle

Update the current account’s handle. Endpoint: com.atproto.identity.updateHandle Authentication: Required
​
handle
string
required
The new handle to use for the account
Response: Empty response on success Example: 
await agent.com.atproto.identity.updateHandle({
  handle: 'newalice.bsky.social'
})

curl -X POST https://bsky.social/xrpc/com.atproto.identity.updateHandle \
  -H "Authorization: Bearer $ACCESS_JWT" \
  -H "Content-Type: application/json" \
  -d '{"handle": "newalice.bsky.social"}'

​
requestPlcOperationSignature

Request a signature for a PLC operation from the PDS. Endpoint: com.atproto.identity.requestPlcOperationSignature Authentication: Required Response: Returns signature data for submitting a PLC operation.

​
signPlcOperation

Sign a PLC operation. Endpoint: com.atproto.identity.signPlcOperation Authentication: Required Used to sign operations for modifying DID:PLC documents.

​
submitPlcOperation

Submit a signed PLC operation. Endpoint: com.atproto.identity.submitPlcOperation Authentication: Required Submits a signed operation to update a DID:PLC document.

​
refreshIdentity

Refresh the cached identity information for an account. Endpoint: com.atproto.identity.refreshIdentity Authentication: Required Triggers the PDS to refresh cached handle and DID document information.

​
Type Definitions

​
identityInfo

Complete identity information including DID, handle, and DID document.
​
did
string
required
The DID of the identity
​
handle
string
required
The validated handle, or handle.invalid if validation failed
​
didDoc
object
required
The complete DID document

​
Common Use Cases

​
Resolving a User by Handle

// Resolve handle to DID
const { data } = await agent.com.atproto.identity.resolveHandle({
  handle: 'alice.bsky.social'
})

const did = data.did

// Use DID to fetch profile
const profile = await agent.app.bsky.actor.getProfile({
  actor: did
})

​
Updating Your Handle

// Update to custom domain
await agent.com.atproto.identity.updateHandle({
  handle: 'alice.com'
})

// Verify the update
const session = await agent.com.atproto.server.getSession()
console.log(session.data.handle) // alice.com

​
Bi-directional Validation

Handles must validate bi-directionally:
  1. Handle → DID: DNS TXT record or HTTPS file points to DID
  2. DID → Handle: DID document alsoKnownAs field includes handle
If validation fails in either direction, the handle is marked as handle.invalid.

​
Resources