Implementing ePDS Login

ePDS lets your users sign in to AT Protocol apps — like Bluesky — using familiar login methods: email OTP, Google, GitHub, or any other provider Better Auth supports. Under the hood it is a standard AT Protocol PDS wrapped with a pluggable authentication layer. Users just sign in with their email or social account and get a presence in the AT Protocol universe (a DID, a handle, a data repository) automatically provisioned.

From your app's perspective, ePDS uses standard AT Protocol OAuth (PAR + PKCE + DPoP). The reference implementation is packages/demo in the ePDS repository.

Two Flows

	Flow 1	Flow 2
App collects email?	Yes	No
PAR includes	Nothing extra	Nothing extra
Auth server shows	OTP input directly	Email form first
Redirect includes	`&login_hint=<email>`	Nothing extra

Important: login_hint must never go in the PAR body when the value is an email address. The PDS core (AT Protocol layer) validates login_hint as an ATProto identity (handle like user.bsky.social or DID like did:plc:…) and rejects email addresses with Invalid login_hint. Put login_hint only on the auth redirect URL — that request goes to the ePDS auth service (Better Auth layer), which accepts emails and uses them to skip the email-collection step.

Quick Start

1. Client Metadata

Host at your client_id URL (must be HTTPS in production):

{
  "client_id": "https://yourapp.example.com/client-metadata.json",
  "client_name": "Your App",
  "redirect_uris": ["https://yourapp.example.com/api/oauth/callback"],
  "scope": "atproto transition:generic",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "dpop_bound_access_tokens": true
}

Optional branding fields: logo_uri, email_template_uri, email_subject_template, brand_color, background_color.

2. Login Handler

// GET /api/oauth/login?email=user@example.com  (Flow 1)
// GET /api/oauth/login                         (Flow 2)

const { privateKey, publicJwk, privateJwk } = generateDpopKeyPair()
const codeVerifier = generateCodeVerifier()
const codeChallenge = generateCodeChallenge(codeVerifier)
const state = generateState()

const parBody = new URLSearchParams({
  client_id: clientId,
  redirect_uri: redirectUri,
  response_type: 'code',
  scope: 'atproto transition:generic',
  state,
  code_challenge: codeChallenge,
  code_challenge_method: 'S256',
})

// PAR always requires a DPoP nonce retry — handle it:
let parRes = await fetch(PAR_ENDPOINT, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    DPoP: createDpopProof({
      privateKey,
      jwk: publicJwk,
      method: 'POST',
      url: PAR_ENDPOINT,
    }),
  },
  body: parBody.toString(),
})
if (!parRes.ok) {
  const nonce = parRes.headers.get('dpop-nonce')
  if (nonce && parRes.status === 400) {
    parRes = await fetch(PAR_ENDPOINT, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        DPoP: createDpopProof({
          privateKey,
          jwk: publicJwk,
          method: 'POST',
          url: PAR_ENDPOINT,
          nonce,
        }),
      },
      body: parBody.toString(),
    })
  }
}

const { request_uri } = await parRes.json()

// Save state in signed HttpOnly cookie (maxAge: 600 to match request_uri lifetime)
const loginHintParam = email ? `&login_hint=${encodeURIComponent(email)}` : ''
const authUrl = `${AUTH_ENDPOINT}?client_id=${encodeURIComponent(clientId)}&request_uri=${encodeURIComponent(request_uri)}${loginHintParam}`
// redirect to authUrl

3. Callback Handler

// GET /api/oauth/callback?code=...&state=...

const {
  codeVerifier,
  dpopPrivateJwk,
  state: savedState,
} = getSessionFromCookie()
if (params.state !== savedState) throw new Error('state mismatch')

const { privateKey, publicJwk } = restoreDpopKeyPair(dpopPrivateJwk)

// Token exchange — also requires DPoP nonce retry:
let tokenRes = await fetch(TOKEN_ENDPOINT, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    DPoP: createDpopProof({
      privateKey,
      jwk: publicJwk,
      method: 'POST',
      url: TOKEN_ENDPOINT,
    }),
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code,
    redirect_uri: redirectUri,
    client_id: clientId,
    code_verifier: codeVerifier,
  }).toString(),
})
if (!tokenRes.ok) {
  const nonce = tokenRes.headers.get('dpop-nonce')
  if (nonce) {
    tokenRes = await fetch(TOKEN_ENDPOINT, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        DPoP: createDpopProof({
          privateKey,
          jwk: publicJwk,
          method: 'POST',
          url: TOKEN_ENDPOINT,
          nonce,
        }),
      },
      body: /* same body */ '',
    })
  }
}

const { sub: userDid } = await tokenRes.json()
// sub is a DID e.g. "did:plc:abc123..." — resolve to handle via PLC directory

Common Pitfalls

Pitfall	Fix
Flash of email form	Include `login_hint` on the auth redirect URL only (never in the PAR body)
`Invalid login_hint` from PAR	Remove `login_hint` from the PAR body — PDS core only accepts ATProto handles/DIDs, not emails
`auth_failed` immediately	Check Caddy logs — likely a DNS/upstream name mismatch
DPoP rejected	Always implement the nonce retry loop (ePDS always demands a nonce)
`Cannot find package` in tests	Run `pnpm build` before `pnpm test` — vitest needs `dist/`
Token exchange fails	Restore the DPoP key pair from the session cookie, don't generate a new one
Double OTP email	Normal on duplicate GET — `otpAlreadySent` flag suppresses auto-send on reload

Handles

ePDS generates random handles, not email-derived ones. When a user signs up with alice@example.com, their handle will be something like a3x9kf.pds.example (random prefix + PDS hostname), not alice.pds.example. Resolve the handle from the DID via the PLC directory after login (shown in the callback handler).

ePDS Endpoints (defaults)

PAR:   https://<pds-hostname>/oauth/par
Auth:  https://auth.<pds-hostname>/oauth/authorize
Token: https://<pds-hostname>/oauth/token

Reference Files

PKCE and DPoP helpers — full TypeScript implementations
Client metadata fields — all supported fields including email branding
Full flow walkthrough — sequence diagrams and step-by-step for both flows

epds-login