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.server namespace provides lexicons for account creation, authentication, session management, and server configuration.

​
Key Concepts

  • Account: User account on a Personal Data Server (PDS)
  • Session: Authenticated connection with access and refresh tokens
  • App Password: Scoped authentication token for third-party apps
  • Invite Code: Code required to create new accounts (optional)

​
Account Creation

​
createAccount

Create a new account. Endpoint: com.atproto.server.createAccount
​
email
string
Email address for the account
​
handle
string
required
Requested handle for the account
​
did
string
Pre-existing DID being imported to new account
​
inviteCode
string
Invite code (if required by server)
​
verificationCode
string
Verification code from email or SMS
​
verificationPhone
string
Phone number for verification
​
password
string
Initial account password
​
recoveryKey
string
DID PLC rotation key for account recovery
​
plcOp
object
Signed DID PLC operation for account migration
Response:
​
accessJwt
string
required
Access token for API requests
​
refreshJwt
string
required
Refresh token for obtaining new access tokens
​
handle
string
required
Account handle
​
did
string
required
Account DID
​
didDoc
object
Complete DID document
Example: 
const response = await agent.com.atproto.server.createAccount({
  email: 'alice@example.com',
  handle: 'alice.bsky.social',
  password: 'secure-password-123'
})

console.log('Account created:', response.data.did)

curl -X POST https://bsky.social/xrpc/com.atproto.server.createAccount \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "handle": "alice.bsky.social",
    "password": "secure-password-123"
  }'
Errors:
  • InvalidHandle: Handle does not meet requirements
  • InvalidPassword: Password does not meet requirements
  • InvalidInviteCode: Invite code is invalid or expired
  • HandleNotAvailable: Handle is already taken
  • UnsupportedDomain: Domain is not supported by server

​
deleteAccount

Delete an account. Endpoint: com.atproto.server.deleteAccount Authentication: Required
​
did
string
required
DID of the account to delete
​
password
string
required
Account password for confirmation
​
token
string
required
Token from requestAccountDelete

​
requestAccountDelete

Request account deletion (sends confirmation token). Endpoint: com.atproto.server.requestAccountDelete Authentication: Required

​
deactivateAccount

Temporarily deactivate an account. Endpoint: com.atproto.server.deactivateAccount Authentication: Required
​
deleteAfter
string
ISO 8601 datetime after which account will be permanently deleted

​
activateAccount

Reactivate a deactivated account. Endpoint: com.atproto.server.activateAccount Authentication: Required

​
Session Management

​
createSession

Create an authentication session. Endpoint: com.atproto.server.createSession
​
identifier
string
required
Handle or email for authentication
​
password
string
required
Account password
​
authFactorToken
string
Two-factor authentication token
​
allowTakendown
boolean
Return narrow-scoped token for takendown accounts instead of error
Response:
​
accessJwt
string
required
Access token (short-lived)
​
refreshJwt
string
required
Refresh token (long-lived)
​
handle
string
required
Account handle
​
did
string
required
Account DID
​
didDoc
object
DID document
​
email
string
Account email
​
emailConfirmed
boolean
Whether email is confirmed
​
emailAuthFactor
boolean
Whether email 2FA is enabled
​
active
boolean
Whether account is active
​
status
string
Account status if not active: takendown, suspended, or deactivated
Example: 
const response = await agent.com.atproto.server.createSession({
  identifier: 'alice.bsky.social',
  password: 'secure-password-123'
})

const { accessJwt, refreshJwt } = response.data

curl -X POST https://bsky.social/xrpc/com.atproto.server.createSession \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "alice.bsky.social",
    "password": "secure-password-123"
  }'
Errors:
  • AccountTakedown: Account has been taken down
  • AuthFactorTokenRequired: 2FA token required

​
getSession

Get current session information. Endpoint: com.atproto.server.getSession Authentication: Required Response: Returns current session details including handle, DID, and email. Example: 
const response = await agent.com.atproto.server.getSession()
console.log('Logged in as:', response.data.handle)

​
refreshSession

Refresh an authentication session. Endpoint: com.atproto.server.refreshSession Authentication: Required (using refresh token) Response: Returns new access and refresh tokens. Example: 
// SDK handles this automatically
await agent.com.atproto.server.refreshSession()

​
deleteSession

Delete the current session (logout). Endpoint: com.atproto.server.deleteSession Authentication: Required Example: 
await agent.com.atproto.server.deleteSession()

​
App Passwords

​
createAppPassword

Create an app-specific password. Endpoint: com.atproto.server.createAppPassword Authentication: Required
​
name
string
required
Name for the app password
​
privileged
boolean
Whether this is a privileged app password
Response:
​
name
string
required
App password name
​
password
string
required
Generated app password (only shown once)
​
createdAt
string
required
Creation timestamp
​
privileged
boolean
Whether privileged
Example: 
const response = await agent.com.atproto.server.createAppPassword({
  name: 'My Third Party App'
})

console.log('Save this password:', response.data.password)

​
listAppPasswords

List app passwords for the account. Endpoint: com.atproto.server.listAppPasswords Authentication: Required Response: Array of app passwords (without the actual password values).

​
revokeAppPassword

Revoke an app password. Endpoint: com.atproto.server.revokeAppPassword Authentication: Required
​
name
string
required
Name of the app password to revoke

​
Email Management

​
updateEmail

Update account email address. Endpoint: com.atproto.server.updateEmail Authentication: Required
​
email
string
required
New email address
​
emailAuthFactor
boolean
Whether to enable email 2FA
​
token
string
Token from requestEmailUpdate

​
requestEmailUpdate

Request email update (sends confirmation). Endpoint: com.atproto.server.requestEmailUpdate Authentication: Required

​
confirmEmail

Confirm email address. Endpoint: com.atproto.server.confirmEmail Authentication: Required
​
email
string
required
Email to confirm
​
token
string
required
Confirmation token from email

​
requestEmailConfirmation

Request email confirmation. Endpoint: com.atproto.server.requestEmailConfirmation Authentication: Required

​
Password Management

​
resetPassword

Reset account password. Endpoint: com.atproto.server.resetPassword
​
token
string
required
Token from requestPasswordReset
​
password
string
required
New password

​
requestPasswordReset

Request password reset. Endpoint: com.atproto.server.requestPasswordReset
​
email
string
required
Account email address

​
Server Information

​
describeServer

Get server description and configuration. Endpoint: com.atproto.server.describeServer Response:
​
availableUserDomains
array
required
Available handle domains
​
inviteCodeRequired
boolean
Whether invite codes are required
​
phoneVerificationRequired
boolean
Whether phone verification is required
​
links
object
Important links (privacy policy, terms of service)
Example: 
const response = await agent.com.atproto.server.describeServer()
console.log('Available domains:', response.data.availableUserDomains)

​
checkAccountStatus

Check account status. Endpoint: com.atproto.server.checkAccountStatus Authentication: Required

​
getServiceAuth

Get service authentication token. Endpoint: com.atproto.server.getServiceAuth Authentication: Required
​
aud
string
required
Audience (DID) for the service auth token
​
lxm
string
Lexicon method to grant access to
​
exp
integer
Expiration time (Unix timestamp)

​
Invite Codes

​
getAccountInviteCodes

Get invite codes for the account. Endpoint: com.atproto.server.getAccountInviteCodes Authentication: Required
​
includeUsed
boolean
Include used invite codes
​
createAvailable
boolean
Create new codes if available

​
createInviteCode

Create a single invite code. Endpoint: com.atproto.server.createInviteCode Authentication: Required
​
useCount
integer
required
Number of uses allowed
​
forAccount
string
Restrict to specific account

​
createInviteCodes

Create multiple invite codes. Endpoint: com.atproto.server.createInviteCodes Authentication: Required
​
codeCount
integer
required
Number of codes to create
​
useCount
integer
required
Uses per code
​
forAccounts
array
Restrict codes to specific accounts

​
Type Definitions

​
inviteCode

Invite code information.
​
code
string
required
The invite code
​
available
integer
required
Remaining uses
​
disabled
boolean
required
Whether disabled
​
forAccount
string
required
Restricted to account
​
createdBy
string
required
Creator DID
​
createdAt
string
required
Creation timestamp
​
uses
array
required
Array of invite code uses

​
Common Use Cases

​
Complete Authentication Flow

// 1. Create session
const session = await agent.com.atproto.server.createSession({
  identifier: 'alice.bsky.social',
  password: 'password123'
})

// 2. Store tokens
localStorage.setItem('accessJwt', session.data.accessJwt)
localStorage.setItem('refreshJwt', session.data.refreshJwt)

// 3. Make authenticated requests
// SDK handles token refresh automatically

// 4. Logout
await agent.com.atproto.server.deleteSession()

​
Using App Passwords

// Create app password
const appPass = await agent.com.atproto.server.createAppPassword({
  name: 'Mobile App'
})

// User logs in with app password
await agent.com.atproto.server.createSession({
  identifier: 'alice.bsky.social',
  password: appPass.data.password
})

​
Resources