Atmosphere Login SDK reference — Atmosphere Account Docs

Browser

Static browser SDK

GET/atmosphere-login.js

Enhances [data-atmosphere-login] buttons and exposes window.AtmosphereLogin helpers.

Attribute	Type	Purpose
data-atmosphere-login	boolean	Enhance this element as a Continue with Atmosphere button.
data-client-id	URL	Registered app client ID and selection-token audience.
data-return-uri	URL	Exact callback receiving the selection token.
data-scope	string	Optional picker context. App OAuth scopes are still separate.
data-state	string	Optional caller-provided nonce. If omitted, SDK generates one.
data-mode	`redirect` \| `popup`	Redirect is the default and most reliable flow. Popup mode dispatches `atmosphere-login:complete` after origin, client, and state checks pass.
data-app-name	string	Fallback label/accessibility context.
data-app-homepage	URL	Fallback local metadata; registered metadata wins in picker identity.
data-atmosphere-origin	URL	Use a non-production Atmosphere deployment during local development.

Browser helpers

const built = AtmosphereLogin.buildUrl({
  clientId: "https://app.example.com/oauth/client-metadata.json",
  returnUri: "https://app.example.com/auth/atmosphere/selected",
  scope: "atproto",
});

AtmosphereLogin.continueWithAtmosphere({
  clientId: "https://app.example.com/oauth/client-metadata.json",
  returnUri: "https://app.example.com/auth/atmosphere/selected",
});

const selection = AtmosphereLogin.consumeSelection({
  clientId: "https://app.example.com/oauth/client-metadata.json",
  expectedState: stateFromSession,
});

// By default, consumeSelection removes Atmosphere Login callback parameters
// from the address bar after reading them. Pass { clearUrl: false } only if
// your router needs to control URL cleanup itself.
//
// In popup mode, the callback page also posts the selection to window.opener.
// The opener SDK dispatches "atmosphere-login:complete" after validating the
// message origin, client ID, and state.

Server verifier

GET/atmosphere-login-server.js

ES module helper for server-side callback verification in Deno, Node-compatible runtimes, and examples.

Export	Purpose
fetchAtmosphereLoginPublicJwkForToken(token, origin)	Fetches the public key whose `kid` matches the returned selection token. JWKS is cached briefly and refreshed on key miss.
fetchAtmosphereLoginPublicJwk(origin)	Fetches a public key from `/oauth/jwks.json`; pass `{ kid }` when selecting explicitly. Supports `{ cache: false }` and `{ cacheTtlMs }`.
verifyAtmosphereLoginCallback(options)	Reads callback params and verifies the embedded selection token.
verifyAtmosphereSelectionToken(options)	Verifies a raw selection token against a JWK and expected claims.

Picker request parameters

Parameter	Required	Meaning
client_id	Yes	Registered app client ID.
return_uri	Yes	Exact callback URL for the selection token.
state	Yes	App nonce returned in params and token claims.
scope	No	Picker context; not an app OAuth grant.

Callback payload

Query parameters

selection_token=eyJ...
client_id=https://app.example.com/oauth/client-metadata.json
state=generated-state
did=did:plc:...
handle=alice.example
iss=https://login.atmosphereaccount.com

Token claim	Meaning
iss	Atmosphere deployment that signed the token.
aud	Registered app client ID.
sub	Selected ATProto account DID.
handle	Selected account handle at selection time.
pds_url	Optional known host/PDS hint.
return_uri	Callback URL the token was delivered to.
state	App nonce.
app_name	Picker app identity shown to the user.
iat / exp	Short token lifetime.
jti	Replay key.

Verifier errors

Error	Usually means
missing selection_token	The callback URL is wrong or the picker did not complete.
client_id parameter mismatch	The callback does not match the expected app.
state parameter mismatch	The app lost or changed the initiating nonce.
invalid signature	The token is malformed or signed by the wrong key.
issuer mismatch	The expected Atmosphere deployment is wrong.
audience mismatch	The token was not minted for this app client ID.
return URI mismatch	The callback does not match the token claim.
replayed token	The `jti` has already been used.

Static browser SDK

Server verifier

Picker request parameters

Callback payload

Verifier errors

Keep building