Install
Use the static browser SDK
<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-scope="atproto"
data-app-name="Example App"
data-app-homepage="https://app.example.com"
></button>| Attribute | Required | Purpose |
|---|---|---|
| data-atmosphere-login | Yes | Marks the button for SDK enhancement. |
| data-client-id | Yes | Audience for the selection token. |
| data-return-uri | Yes | Callback that receives the selection token. |
| data-scope | No | Optional picker context. Your app OAuth still owns scopes. |
| data-mode | No | redirect by default, or popup. |
| data-app-name | No | Local accessibility fallback; registered metadata wins in picker identity. |
Build the URL yourself
const { url, state } = AtmosphereLogin.buildUrl({
clientId: "https://app.example.com/oauth/client-metadata.json",
returnUri: "https://app.example.com/auth/atmosphere/selected",
scope: "atproto",
});
sessionStorage.setItem("atmosphere_state", state);
location.href = url;Popup mode
Redirect is still the default
Use popup mode only when it materially improves your desktop web app. The SDK centers it and adapts its size to the available screen, but browsers can block popups unless they start from a direct user action, promote them to full tabs, and prevent completion events under strict opener isolation headers.
Mobile launch behavior
Mobile websites should keep the default same-tab redirect. Native apps should open the picker in ASWebAuthenticationSession or an Android Custom Tab and return through an app/universal link rather than using the JavaScript popup API.
const button = document.querySelector("[data-atmosphere-login]");
button.addEventListener("atmosphere-login:complete", (event) => {
const { selection } = event.detail;
// Verify selection.token on your server before starting your app sign-in.
});
button.addEventListener("atmosphere-login:cancel", () => {
// The user closed the picker before choosing an account.
});const selection = AtmosphereLogin.consumeSelection({
clientId: "https://app.example.com/oauth/client-metadata.json",
closePopup: true,
});
if (!selection) {
// Show a small fallback message or return to your app.
}See it in the reference app
The example app includes a popup-mode button. Its popup callback posts the selection back to the opener, then the opener navigates through the same server-verified callback used by redirect mode.