Build your first Atmosphere Login flow — Atmosphere Account Docs

Flow

Atmosphere selects, your app authorizes

The picker only answers one question: which Atmosphere account does the user want to use? Your app still owns scopes, grants, sessions, refresh behavior, and logout.

01Render button

Use the browser SDK or build /login/select yourself.

02Receive callback

Atmosphere returns selection_token, client_id, state, and account hints.

03Verify selection

Check the signed token and reject stale, replayed, or mismatched callbacks.

04Start OAuth

Begin AT Protocol OAuth with the selected handle or DID as login_hint.

Local development wording

Developers usually run a local app while integrating. ATProto’s development shortcut uses http://localhost/ as a special client ID, while local callbacks should use loopback IP return URIs such as http://127.0.0.1:5173/callback. Production uses exact HTTPS return URIs.

Minimal implementation

Register app identity

Create a development or production app registration with a name, client ID, homepage, logo, and allowed return URI.

Add the SDK button

Pass the registered client ID, return URI, and app metadata to the browser SDK.

Verify the callback

Use the server helper or your own JWT verifier to validate the selection token.

Continue OAuth

Start AT Protocol OAuth and verify the returned sub DID according to the AT Protocol OAuth profile.

Button

<script src="https://login.atmosphereaccount.com/atmosphere-login.js" defer></script>

<button
  data-atmosphere-login
  data-client-id="https://app.example.com/oauth/client-metadata.json"
  data-return-uri="https://app.example.com/auth/atmosphere/selected"
  data-app-name="Example App"
></button>

Selection callback

const verified = await verifyAtmosphereLoginCallback({
  url: request.url,
  publicJwk,
  expectedIssuer: "https://login.atmosphereaccount.com",
  expectedClientId,
  expectedReturnUri,
  expectedState,
  replayStore,
});

if (!verified.ok) throw new Error(verified.error);

return startAtprotoOAuth({
  loginHint: verified.claims.handle || verified.claims.sub,
});

Move from local dev to production

Local URLs are for integration only. Before requesting trust, move every public identity and return URI to HTTPS.

Use a production HTTPS client ID URL.
Use exact HTTPS allowed return URIs for every callback.
Serve a recognizable HTTPS logo.
Publish /.well-known/atmosphere-login.json on the app homepage origin.
Run production checks from the app detail page.
Request trusted review only after the picker test passes.