Skip to Content
bsky

πŸ” Authentication

How @kud/bsky signs in with a Bluesky App Password, caches the session, and exposes the raw xrpc helper.

Credentials

The library reads two environment variables:

VariableValue
BLUESKY_HANDLEYour handle, for example alice.example.com
BLUESKY_APP_PASSWORDAn App Password from Bluesky, Settings, App Passwords
export BLUESKY_HANDLE=alice.example.com
export BLUESKY_APP_PASSWORD=<app-password>

Use an App Password, never your account password. You can revoke one at any time from the same settings screen.

Both variables are read once, when the package is first imported. Set them before the import runs (or before your process starts); changing process.env afterwards has no effect.

Sessions

getSession() calls com.atproto.server.createSession on https://bsky.social and returns:

type Session = { accessJwt: string; did: string; handle: string }

The result is cached for the lifetime of the process, so only the first authenticated call logs in. Every function that needs a session calls getSession() for you; you rarely need it directly.

Errors are plain Errors:

  • Missing variables: Missing credentials. Set BLUESKY_HANDLE and BLUESKY_APP_PASSWORD ...
  • Rejected login: Auth failed (<status>): <body>

The server is fixed at PDS = "https://bsky.social", which is also exported. Accounts hosted on a different PDS are not configurable.

The xrpc helper

Every other module is built on xrpc, which is exported if you need an endpoint the library does not wrap:

import { xrpc } from "@kud/bsky"

const result = await xrpc<{ did: string }>(
  "com.atproto.identity.resolveHandle",
  { params: { handle: "alice.example.com" }, auth: false },
)
OptionDefaultMeaning
method"GET""GET" or "POST"
paramsnoneQuery string values; undefined entries are dropped
bodynoneJSON body, sent only for POST
authtrueAttach the bearer token; set false for public endpoints

A non-2xx response throws <nsid> failed (<status>): <body>.