Developer documentation
Build sign-in. Prove it connects.
Integration guides live here. Use your app’s dashboard for login choices, callbacks, readiness and connection tests.
Framework guides
Next.js, React, React Router, Nuxt, Vue and JavaScript hosted web recipes; Expo, Swift and native JavaScript PKCE guidance. Choose your framework and client type →
Enterprise OIDC & SCIM
Isolated workplace sign-in and User provisioning. Setup, supported protocol subset and security boundaries →
Webhooks
Receive signed, app/environment-scoped Auth events with durable retries. Receiver integration, signature validation and operator setup →
Quickstart
- Click New App and enter its name, choose Web or Mobile App and select your framework. Review the suggested permanent ID. The short form creates an app with no trusted return URLs. Save the server key if shown; mobile clients receive no secret.
- Use the Next Step card on App Overview to open the setting that needs attention. Open Sign-in methods to review app-wide choices, then Environments to save an exact callback for Development, Staging or Production. Local web testing uses a loopback address. Native apps need their own registered app return handler.
- Open API Keys from App Overview for the matching framework configuration. Keep server keys on the backend. Public native clients use S256 PKCE and secure token storage. Full integration instructions are in Framework guides.
- Open Sign-in methods and its connection-testing link. Add the client test helper and complete a real authorized return and accepted session. Saved settings, copied code and page visits never mean Verified. The dashboard reads fresh, target-specific evidence.
Replace your-app-id and example callbacks with your own saved values. API keys belong only on a trusted server; public native clients receive no client secret or API key.
Hosted web sign-in
Redirect to Auth with your app ID and an exact approved callback. Your app’s saved methods determine the choices shown. Keep environment-specific verification keys on your backend.
Start hosted login
const loginUrl = new URL('https://auth.aelith.ai/login')
loginUrl.searchParams.set('app', 'your-app-id')
loginUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback')
window.location.assign(loginUrl.toString())The existing hosted flow returns a token in the callback URL. Treat it as untrusted until your backend verifies it; avoid logging callback URLs and remove the token from browser history after processing it. Create your own application session only after verification.
// Server-side token verification (any language/framework)
const res = await fetch('https://auth.aelith.ai/api/verify', {
method: 'POST',
headers: {
'x-api-key': process.env.AELITH_API_KEY!,
'Content-Type': 'application/json',
},
body: JSON.stringify({ token }),
})
const { valid, userId, email } = await res.json()
if (!valid) {
return Response.json({ error: 'Unauthorized' }, { status: 401 })
}
// userId → your user's stable ID (cuid)
// email → user email when availableHosted verification checks the live Auth session, including revocation. Local JWKS verification checks signature, issuer, audience and expiry; it does not independently query session revocation. A token diagnostic is not a verified connection.
Hosted authorization-code pilot
This opt-in server-backed web flow keeps the Auth access token out of callback URLs. It supports Email sign-in/signup/verification, Solana Web3 Wallet message signing, GitHub OAuth, Apple and Google web authorization with existing MFA. Native PKCE is unchanged. Passkeys and enterprise hosted sign-in still use their existing integration; they are not migrated by this pilot.
Apple web sign-in uses a separate cross-site POST proof, then a one-use AUTH return step requiring the original browser cookie before a code can be issued. This is not the native Apple sheet. Browser cookie restrictions can require restarting from your app; do not weaken cookie security.
Operator setup required: apply this release’s additive hosted-code migration before setting HOSTED_CODE_FLOW_ENABLED=true and redeploying. The flag defaults off. Developers cannot enable this platform flag from app settings. Turning it off disables new starts and exchanges; it does not invalidate already issued sessions or disable legacy login. Never fall back to a token callback when a code exchange fails.
- In Sign-in methods, enable the intended Email, Web3 Wallet, GitHub, Apple or Google method for this app and Save if you intend to offer it. This is an app-wide choice; it does not mean a connection test has passed.
- In Environments, register an exact HTTPS callback owned by your app. Development alone can use HTTP on localhost or a loopback address. A callback must belong to exactly one active environment; do not put
code,state,iss,errorortokenin its fixed query string. - In API Keys, use a backend key for that same environment. App-wide legacy keys are not accepted by the new exchange. Keep it on your server, never in React, browser JavaScript, Expo, Swift or public environment variables.
- Download the Node.js source helper below and install
josein your backend. There is no new published SDK or framework adapter. CallbeginHostedSignInon the server withprovider: emailorprovider: walletorprovider: githuborprovider: appleorprovider: google; the existingbeginHostedEmailwrapper stays Email-only. Wallet requires a compatible Solana software wallet with message signing and never requests a transaction. Store its transaction in your server session, bound to the initiating browser with a Secure, HttpOnly, SameSite=Lax session cookie, for at most ten minutes; redirect to its URL. - Your backend callback must atomically take and delete that transaction, including on cancellation or errors. Call
finishHostedSignInwith the complete callback URL, stored transaction and environment server key. It checks the exact callback, state, issuer, nonce, signed token and live Auth session. Never log the callback, code, verifier, key or token. Disable query-string logging at proxies too. - Create your app’s own server session only after validation. Store the Auth token on your server and use a fresh opaque HttpOnly cookie for your app; do not return it to browser JavaScript. Redirect to a clean local URL with no code. Access expires after 15 minutes; no web refresh token is included. Reauthenticate on expiry, clear your app session on logout, and check live session state for sensitive requests.
- For a developer connection test, create an Email/Web or Wallet/Web, GitHub/Web, Apple/Web or Google/Web ticket from Sign-in methods → Connection testing. Use the backend helper’s beginHostedConnectionTest with the matching provider instead of the legacy browser launch helper. Keep its transaction and proof on your server; render only its launch action and fields as an escaped POST form. After finishHostedSignIn, use establishHostedAppSession with your real durable session store, set the returned HttpOnly cookie and redirect to a clean app page. Use a different clean path, such as /signed-in. On that subsequent GET, acknowledgeHostedAppSession must read the stored session selected by the returned cookie before it can acknowledge. Code issuance, exchange and writing a cookie header alone never mean Verified. Never move the Auth token into browser JavaScript to reuse the legacy helper.
On the test-launch form page, preserve the browser’s Origin with strict-origin-when-cross-origin; a global no-referrer or same-origin policy can make a cross-origin form POST send a null Origin, which AUTH rejects. Keep no-referrer on the callback page. Do not relax the server’s Origin checks.
Lost acknowledgment responses are retryable with the same receipt, server key and app session for five minutes, within test/session expiry. The helper retries once; verification_confirmation_unknown means confirmation is unavailable, not that the test failed. Confirmed success with cleanupPending means only local receipt cleanup needs retrying. Retries do not create or change verification evidence.
The code-aware test requires an authenticated environment-specific app backend. AUTH validates its key, test proof and live correlated session, and records a hash of the app session identifier. The backend remains responsible for truthful session storage/readback; this is integration evidence, not remote attestation of arbitrary app code. Synthetic local tests do not mark a production app Verified.
An interrupted request should restart from your app. Opening a second same-app sign-in replaces this browser’s proof; older attempts fail safely. Use a backend callback with no third-party resources and Referrer-Policy: no-referrer. Legacy clients remain compatible but retain their existing token-in-URL risk until individually migrated and tested.
Native apps · S256 PKCE
Register a public mobile client and its exact custom URL scheme or supported app link. Configure that handler in your app target. Use the system authentication session for hosted providers; do not embed a client secret or replace it with a webview.
- Create a fresh high-entropy PKCE verifier, its SHA-256 base64url challenge, state and nonce. Retain the original binding through the attempt.
- Start authorization at
/api/oauth/authorizewith the parameters below. Supported provider values are email, wallet, Apple, Google and passkey when enabled and configured. Native GitHub is not implemented. - Receive only a one-time code and state at the exact callback. Validate state, then POST the code and original verifier to
/api/oauth/token. - Validate the session with bearer-authenticated POST
/api/oauth/session?client_id=your-app-id. Keep accepted tokens in platform secure storage, such as Keychain on iOS. Revoke with POST/api/oauth/revoke?client_id=your-app-idon sign-out.
Authorization parameters · use your own fresh binding
client_id=your-app-id
redirect_uri=ai.example.app://auth/callback
response_type=code
provider=apple
code_challenge=BASE64URL_SHA256_OF_ORIGINAL_VERIFIER
code_challenge_method=S256
state=FRESH_RANDOM_STATE
nonce=FRESH_RANDOM_NONCEToken exchange · form-encoded POST to /api/oauth/token
await fetch('https://auth.aelith.ai/api/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
client_id: 'your-app-id',
redirect_uri: 'ai.example.app://auth/callback',
grant_type: 'authorization_code',
code: codeFromCallback,
code_verifier: originalVerifier,
}),
})Access tokens are returned in the response body, never the native callback URL. Sessions last 15 minutes. Refresh tokens are not supported; reauthenticate after expiry. Cancellation, an interrupted attempt or a lost verifier requires a fresh attempt.
Native email and Apple UI
The browser PKCE path and native credential UI are distinct. For in-app email/signup or the native Apple sheet, use Auth’s app-bound JSON credential flow at /api/oauth/native/credentials. Start with the same S256/state/nonce binding and a random proof sent in x-aelith-native-proof; retain the returned request handle. Email actions are login, signup, verify, resend and cancel. Apple exchanges the authorization code through the apple action. Successful authentication returns a one-time code for the same token exchange; it does not return a native session in the callback.
For the Apple sheet, enable Sign in with Apple on the exact Apple App ID, match its audience in Auth, and use the server-generated Apple nonce from the credential start response. Never put Apple signing keys in the app. Operator rollout configuration and provider credentials must be ready. Your platform integration must handle cancellation and app return before testing.
Login methods and setup
Every app has the same settings catalog. Save changes explicitly. Disabled or unconfigured methods must not appear as usable choices in your app; custom clients need to consume authoritative capabilities. Existing sessions are not signed out by changing visibility.
For native public clients, GET /api/oauth/methods?client_id=your-app-id&platform=ios provides current supported choices. Loading, failed or empty capability responses need an honest retry/unavailable state, not assumed enabled buttons.
Email includes sign-in and Create account under one setting. New users must complete email-code verification. Auth’s operator must configure delivery; an existing-user test does not verify signup mail delivery.
Wallet
Use a supported wallet to sign an authentication message, never a funds transfer. Browser support varies. iOS needs the supported encrypted handoff path. An admin toggle cannot add a wallet button to a custom app that omits it. See the Wallet SDK guide.
GitHub
Hosted web requires operator-configured GitHub OAuth and your app’s registered Auth callback. Native GitHub is not implemented; a guide or enabled legacy setting cannot supply missing native support.
Apple
The Auth operator configures Apple’s Services ID, server callback and signing credentials. Your app separately registers its Auth return URL. The native Apple sheet also needs the exact App ID capability, configured audience and provisioning described in Native PKCE.
The Auth operator configures Google’s OAuth client and Auth server callback. Your app receives Auth’s result through its own registered return handler. No Google client secret belongs in browser or mobile code. Unconfigured Google remains unavailable.
Local wallet SDK
For web apps that connect and sign locally, scaffold a new app or install the existing Auth Core package. This is separate from native PKCE and from the developer-only connection-test helper.
New app
npm create aelith-app@latest my-aelith-appExisting app
npm install @aelith/auth-core@^0.1.3Environment · server key stays private
NEXT_PUBLIC_AELITH_APP_ID=your-app-id
NEXT_PUBLIC_AELITH_AUTH_ORIGIN=https://auth.aelith.ai
AELITH_API_KEY=your_server_side_api_keyWallet client · your own session endpoint
import { AelithAuthClient } from '@aelith/auth-core'
const client = new AelithAuthClient({
appId: 'your-app-id',
authOrigin: 'https://auth.aelith.ai',
})
export async function loginWithAelithWallet(input: {
walletAddress: string
signMessage: (message: Uint8Array) => Promise<Uint8Array>
}) {
const result = await client.loginWithWallet(input)
await fetch('/api/auth/aelith/session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
credentials: 'include',
body: JSON.stringify({ token: result.token }),
})
return result
}Backend verification
const response = await fetch('https://auth.aelith.ai/api/verify', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.AELITH_API_KEY!,
Authorization: `Bearer ${token}`,
},
cache: 'no-store',
})
if (!response.ok) {
throw new Error('Aelith token verification failed.')
}The example /api/auth/aelith/session endpoint belongs to your app: implement it to verify the token and establish your app’s session. It is not an endpoint provided automatically by Auth.
- Connect the wallet on your app’s origin.
- Request a nonce from
/api/sdk/nonce?app=your-app-id&walletAddress=.... - Sign the Auth challenge locally.
- Exchange the signature through
/api/sdk/wallet-login?app=your-app-id. - Verify the returned token on your backend with your app’s server key.
App user management and access policies
App owners and portal Admin collaborators can use the app’s Users page to search scoped users, review available sign-in history and sessions, suspend/restore app access, or revoke one/all sessions in an environment. Developer and Viewer collaborators do not gain private-user management permission. End-user organization roles are separate and never grant portal access.
Operator rollout
- Apply the reviewed additive AppUserAccess migration before deploying its server code. After approval, set
USER_MANAGEMENT_ENABLED=trueand redeploy to activate the dashboard/API. No new provider keys or credentials are required by this feature. - Policy enforcement remains active independently of the dashboard flag. Disabling the UI does not unsuspend users, clear revocation cutoffs or restore old sessions. Do not remove policy data or roll back to server code that ignores access policies after using suspension.
Manage users safely
- Choose the exact app environment. Configure unique registered callbacks and establish fresh scoped native/hosted logins. Historical sessions with unknown scope cannot be assigned to production by guessing. The private list contains only users associated with that app/environment, not a global email directory.
- Search by user ID, display name or verified contact email. Results are limited to 50 per page. Details show the latest 50 sessions and 100 available events, subject to existing log-retention policy. Device labels are reported user-agent metadata, not proof of a physical device or location.
- Access/session changes require Auth portal authentication within five minutes. Suspending revokes existing sessions and refuses new grants/refresh in the selected scope. Restoring access permits a new sign-in; it never resurrects old tokens or pending proofs. Revoke one session for granular logout, or revoke scoped sessions to require fresh authentication.
- Other apps and the global Auth identity remain unchanged. Historical tokens without a proven environment are conservatively refused if they could bypass a restriction in this app; migrate those integrations to scoped sign-in. Private backend verification must bind its API key environment to the session’s known environment. Offline JWT checks alone cannot observe server-side suspension or revocation.
App administrators cannot use this interface to reset someone’s global password, link identities, delete their Auth account or obtain platform-admin privileges. Actions are audited with app, environment, actor and target IDs. No actual account or production policy is changed by local fixtures, and an Active access status does not mean a login connection is Verified.
Account connections and safe unlinking
Explicit connections add proven credentials to one existing Auth account. Matching email addresses never merge separate accounts, overwrite a wallet owner or attach an existing provider account silently.
Account holder steps
- Open Connected sign-in methods after signing in within five minutes. Check the displayed account. App bearer tokens cannot change global account security. A native user can open the trusted account-security journey from the app and follow its Connected sign-in methods link; any required existing MFA must complete first.
- For configured Apple or Google, choose Connect, verify the provider account and confirm the specific connection back on Auth. No email match is treated as proof. For a wallet, connect a compatible message-signing wallet locally, then separately choose Confirm wallet connection. Review Auth’s origin, your account, wallet, random request and three-minute expiry in the message. This is not the ordinary login message and does not authorize a blockchain transaction.
- Changing wallets or cancelling interrupts connection. A failed or uncertain result is not success: sign in again and check current methods before retrying. Existing wallet-owned accounts cannot be merged or reassigned. Wallet connection signs out old Auth sessions.
- Disconnect only after another configured, usable primary method exists. Removing a password keeps the verified contact address but disables password login/reset for it; it does not enroll a new password. Apple is currently disabled for Auth portal primary sign-in, so its identity alone is not a portal recovery route. Unconfigured Google/GitHub and inactive passkeys do not count. MFA recovery codes are second factors, not replacement primary logins.
Operator and developer setup
The wallet/unlink release needs its additive wallet-intent migration plus ACCOUNT_LINKING_ENABLED=true after approved deployment. This controls new wallet connections and unlinking, preserving the existing Apple/Google connection flow. No keys or external wallet grants are created by setup. Keep existing provider credentials and the reviewed trusted origin configuration. New source SDK helpers are not in already published packages automatically.
Account connections occur on trusted Auth pages with HttpOnly browser or dedicated short-lived security-purpose cookies. A third-party app token cannot grant this authority, change another account’s connections or choose an app/environment to bypass it. Do not embed account credentials, private keys or server API keys in client apps. Native users still need the shared account-security browser journey; this is not an in-app wallet-login button added to Eluvi.
Implemented new connection types: Wallet, plus the existing Apple/Google verified-provider flow. Existing email/password and GitHub primary methods can be disconnected safely, but connecting a new email/password or GitHub identity to an existing account is not implemented here. Separate accounts require a future explicit recovery/link flow; signup and password reset must not be used as a substitute.
End-user organizations and invitations
Organizations are app- and environment-scoped end-user tenants. Their Owner, Admin and Member roles never grant Auth developer-portal collaborator permissions. The signed-in app session determines scope; callers cannot select a different environment or target user. Register a distinct callback for each environment and establish a new scoped native or hosted sign-in after activation. Older sessions, ambiguous callbacks and local wallet SDK sessions without proven environment scope cannot manage organizations; use scoped hosted sign-in rather than guessing a production environment.
Platform setup
After the additive organizations migration and reviewed server deployment, an operator can activate ORGANIZATIONS_ENABLED=true. This local feature stage is not a claim that your production installation is active.
Integrate your app
- Use your user’s app-scoped Auth access token with
/api/organizations?client_id=your-app-id. Cookie-free native runtimes may call directly. Browser apps must proxy through their own authenticated backend; cross-origin browser and portal-cookie requests are rejected. Never expose a server API key. - The source
AelithOrganizationsclient supports list, details and explicit mutations. The source ReactOrganizationManagementcomponent accepts a scoped adapter. These new helpers require a separately published SDK version or reviewed source integration; they are not in an already installed package automatically. - Creation makes the creator Owner. Owners can transfer ownership to an existing member, then leave. Admins can manage Member invitations/removals but cannot promote roles, remove owners/admins or archive. Members can leave; owner departure requires transfer first. Membership and invitation mutations require primary authentication within five minutes; refresh does not reset that clock.
- Create an invitation with the intended email and Member/Admin role. Auth stores only its code hash, returns the random code once and expires it after 24 hours. Share it securely out of band; Auth does not send email automatically. Never put it in a URL, logs or analytics. The invitee signs in with the same verified email and submits the code in a POST body. Acceptance never links accounts, changes an existing member’s role or grants portal access.
Organization request · native runtime or your web backend
const organizations = new AelithOrganizations(authOrigin, clientId, getAccessToken)
const rows = await organizations.list()
await organizations.mutate({ action: 'create', name: 'My team' })
// No automatic retries after interrupted mutations; refresh and reconcile first.Reissued invitations invalidate older pending codes. Revoked, consumed or expired codes cannot be accepted. Archiving hides the organization and closes outstanding invitations. These memberships do not automatically authorize your business-data queries: your backend must enforce the selected organization and current membership for every tenant-scoped resource. No email delivery, external IdP or existing app integration is verified by these local tests.
Authenticator MFA and recovery codes
MFA is a second factor on an Auth account, not another primary login-method toggle. Once enrolled, it applies across email, wallet, GitHub, Apple, Google and passkey sign-ins for that user. Password recovery does not remove MFA. An enabled login method is still distinct from a successful, Verified app connection.
For platform operators
- Apply the reviewed additive MFA migration before deploying its server release. Configure
MFA_ENCRYPTION_KEYS_JSONas a private JSON array of key entries withidand a canonical base64keycontaining exactly 32 random bytes. SetMFA_ACTIVE_KEY_IDto an entry’s ID. Generate and save keys privately in your approved secret manager; do not paste them into chat, public Docs, client bundles or logs. - Set
MFA_ENABLED=trueand redeploy only when enrollment is approved. This controls new enrollment; disabling it never bypasses MFA on already protected accounts. Missing encryption keys fail closed. Keep old key IDs available for existing factors; automatic key rotation/re-encryption is not implemented. Rollback must retain MFA enforcement once any user enrolls; do not downgrade to pre-MFA login code or remove active factor data. - Set the trusted public origin with
NEXT_PUBLIC_APP_URL. Keep the existing authenticated maintenance job running: it expires challenges/security sessions and pending enrollment, while retaining spent refresh hashes until absolute family expiry. It must not delete usage-bearing session history or active factor secrets.
For account holders
- Open Authenticator and recovery after a recent Auth account sign-in. Check the displayed account before making changes. App bearer tokens cannot change global account security.
- Add the setup key to your authenticator or use Open authenticator. Confirm a code within five minutes; an unconfirmed setup is not enabled. Auth encrypts the shared secret and never receives biometric data.
- Save the ten recovery codes securely when shown. Each works once and cannot be retrieved again. Replace codes before reaching your last one. The default and native/hosted flows require separate unused proofs for sign-in and code replacement. If your operator has enabled portal recovery, the portal can briefly offer a two-phase replacement tied to the last code you just used: save the inactive set, then confirm activation before its deadline. This does not disable MFA or recover an account after all factors are lost. Enabling MFA, disabling it or replacing codes signs out existing sessions. A TOTP code used for setup or another login cannot be reused; wait for the next code or use one recovery code.
- To disable MFA or replace codes, sign in recently and prove an existing factor. A password reset alone cannot bypass this requirement. There is no support shortcut that reveals codes or silently disables MFA if all factors are lost.
For native developers
Native email/Apple proof may return mfa_required=true, an opaque challenge, remaining lifetime and the original state instead of an authorization code. Keep the original in-memory native request proof and PKCE verifier. Render a code/recovery-code form in your app and POST the challenge through the helper below. Match state, then redeem the returned one-time code with the original S256 verifier. Do not report success or store a session before this completes.
Submit one factor attempt at a time; never retry automatically after an uncertain network result. A rejected code can be retried manually with a new code while the challenge is valid. Cancel explicitly when abandoning the flow. A client without MFA UI must fail closed rather than fall back to an unprotected session. Source helpers are available here; older published SDKs and installed apps are not automatically updated.
Native email · optional completion recovery pilot
This versioned pilot is off by default and applies only when the native email MFA response advertises completion_recovery.version=1. It does not add hosted or Apple recovery. Your operator must deploy the receipt migration and reviewed backend before separately enabling NATIVE_EMAIL_MFA_RECOVERY_ENABLED alongside native credentials. Developers cannot enable it with an app toggle.
Retain the original request proof, PKCE verifier, state and nonce. The new helper keeps an independent recovery proof in memory. Submit MFA once; after an uncertain response show an explicit Retry sign-in or Cancel action. At most three manual retries fit within the original expiry and 90 seconds. Each newer retry invalidates earlier unredeemed codes without repeating MFA, extending expiry or creating a session. Lost proof, reload, expiration or exhausted attempts requires a new sign-in.
A returned code still needs one normal exchange and actual app acceptance. A lost token-exchange response is not recovered and must never be labeled successful. If cancellation wins, unfinished codes are fenced. If exchange wins, cancellation reports a conflict; existing sessions remain. These source helpers do not install a native screen or prove that your app stores a session.
Swift also requires the base MFA helper above. Existing clients keep their existing contract; explicit version 1 opt-in fails closed if unavailable. Keep a single helper instance for the attempt, surface its error messages, and do not log or persist factors, proofs, codes or tokens.
Hosted email · optional completion recovery pilot
This email-only version 1 pilot is off by default. It requires a reviewed server migration/deployment and separate operator activation of HOSTED_EMAIL_MFA_RECOVERY_ENABLED. Existing apps keep their existing callback contract; a dashboard toggle alone does not integrate recovery.
Your backend must use beginHostedEmailMfaSignIn and finishHostedEmailMfaSignIn from the reviewed hosted-code helper, with a durable transaction store bound to the initiating HttpOnly browser session. The old take-once callback helper cannot safely handle superseded responses and refuses a marked version 1 transaction. Keep all verifiers, server keys and transaction storage on your backend.
AUTH’s MFA page offers up to three manual Retry sign-in attempts after an uncertain response, within the original code/challenge expiry (normally no more than 60 seconds). A newer retry replaces earlier unredeemed codes without repeating MFA or creating a session. Losing the in-memory proof, reloading, expiration or exhausting retries requires restarting. Cancellation can conflict if exchange already completed.
The backend store must atomically claim one callback, release only after AUTH confirms a known older code caused no exchange, and retain terminal state after every success or uncertain exchange. Never take over an in-progress claim or retry a lost token exchange. The validated result still needs actual app-session storage/readback and the existing test acknowledgment before it can be Verified. This pilot does not install a storage adapter, add Apple recovery or prove live email delivery.
Backend-only integration · implement the durable store contract first
const started = beginHostedEmailMfaSignIn({ authOrigin, clientId, redirectUri })
// Persist started.transaction in your protected backend, bound to this browser.
await browserBoundStore.put(started.transaction)
// On the exact callback, with the same verified browser session:
const result = await finishHostedEmailMfaSignIn({
callbackUrl, store: browserBoundStore, apiKey: environmentServerKey,
})
// Only now persist/read back YOUR app session. No automatic token retry.
// claim(state): pending -> processing, original transaction + random lease
// close(lease): exact-lease terminal tombstone through original expiry
// releaseSuperseded(lease): exact-lease pending only after AUTH's no-exchange resultSource helper download and the hosted code integration guide are available above. Deploy the additive request/receipt migration before the new server code; keep the pilot off until your callback store and real browser integration have been reviewed and tested. Source/package candidates are not automatically published or activated.
Wallet SDK fallback
Direct wallet SDK login does not collect a global MFA code inside a third-party web app. A protected account receives mfa_requires_hosted_login without a session. The core SDK throws HostedMfaRequiredError; build its hosted URL with your exact registered callback and offer an explicit Continue securely button. The React hook exposes requiresHostedLogin and its existing startHostedLogin(callback) action. Hosted wallet login completes the bound second-factor page, then returns through the normal registered callback. Inline SDK MFA is not supported.
Native account management, including Apple-only users
The helper’s account-security bootstrap sends a valid, recently authenticated native bearer only to Auth and returns a lower-power Auth intent URL. Open it in the system browser after user action. It does not return a security token to your app. Auth shows the initiating app, obtains new Apple proof matching the existing linked subject, and requires existing MFA when enabled. A separate, five-minute security-only cookie authorizes account MFA controls. It cannot sign in to the Security Portal or authorize app APIs. This does not guarantee Apple will request Face ID.
Operator setup is separate: add the exact dedicated Apple return URL https://your-auth-origin/api/account-security/apple/callback to the existing intended web Services ID, verify subject grouping with your native App ID, then explicitly enable ACCOUNT_SECURITY_APPLE_ENABLED=true and redeploy. For Aelith’s standard origin the return URL is https://auth.aelith.ai/api/account-security/apple/callback. No Apple portal-owner login is reenabled. This new callback has not been registered or tested live by the local implementation.
The user must sign in again if the native session lacks current scope metadata or is older than five minutes; refresh does not renew primary-authentication time. Accounts without a linked Apple identity use their existing Auth account sign-in instead. Check the account label on the management page and exit the temporary session when finished. After a factor change, return to your app and authenticate again. No account-security authority, setup key or recovery code is sent to the app.
Test before activation
Use authorized test accounts to check enrollment, fresh-code/recovery login, cancellation, expiry, code replay, password reset retaining MFA, logout/relogin, account selection and secure storage. Fixture tests, helper downloads, enabled flags and successful provider redirects are not proof of a live end-to-end integration. Method-specific connection verification still requires the actual accepted app session and its helper acknowledgment. Operator credentials, callback registration and real enrollment require their own approval.
Sessions and native refresh
Account holders can review tracked sessions at Your sessions, revoke one, or sign out everywhere after a recent sign-in. Reported device names are client metadata, not proof of a physical device. Older browser cookies remain untracked until a new sign-in; sign out everywhere invalidates them too.
Operator setup: apply the additive session schema before deploying, then separately activate SESSION_MANAGEMENT_ENABLED and NATIVE_REFRESH_ENABLED. Each is off by default. App owners/admins can opt a public native client into refresh under Access → Native session policy after signing in within five minutes. Save explicitly; no client secret is issued. These are platform controls, not credentials for developers to embed.
- Keep your exact environment callback and S256 PKCE authorization flow. Consume
/api/oauth/methods?client_id=your-app-id;native_refreshreports app and operator readiness. Only a new eligible code grant can issue a refresh credential. - Accept the code exchange response only from your trusted HTTPS Auth origin. Store the complete access/refresh pair atomically in protected storage. Swift clients can use the Keychain helper below; Native JavaScript clients must implement the store contract. Refresh endpoints reject browser-origin/cookie requests; these helpers do not add browser refresh to the existing hosted web session flow. Never place refresh credentials in URLs, logs, analytics, browser localStorage or application bundles.
- Access expires in 15 minutes. Refresh uses a cookie-free form POST to
/api/oauth/tokenwithgrant_type=refresh_token,client_idandrefresh_token. Replace the complete stored pair before releasing waiting requests. One coordinator per session must serialize refresh across tasks/processes; these helpers coordinate only within their own instance. - Never retry a refresh after an uncertain network outcome. The old credential may already be spent. Reuse revokes the whole session family, including previously issued access tokens when checked online. Sign in again after rejection, lost response or storage failure. Refresh has a seven-day idle limit and a 30-day absolute limit, and never renews recent-authentication proof.
- Sign out clears local credentials and form POSTs the refresh token to
/api/oauth/revoke. Revocation works even when refresh issuance is off or the access token expired. If offline, local sign-out succeeds but server revocation is unconfirmed. Show that distinction.
The scoped helper revision requires fresh exchange records bound to the trusted Auth origin and client ID. JavaScript stores must atomically compare scope, session ID and refresh token; Swift uses the origin/client-bound Keychain initializer. Namespace protected storage separately for each origin/client and coordinate across processes. Older unbound records or token-only stores are rejected before a token is exposed, sent or deleted: start a fresh sign-in into a new scoped slot rather than relabeling old tokens. Local scope metadata is not JWT verification. Adopt the new store contract before upgrading the helper.
Refresh is bound to the immutable app, environment and exact callback. Removing or disabling that environment/callback rejects refresh; a replacement environment cannot inherit it. Disabling the app policy revokes its refresh sessions. Existing issued access tokens remain usable until their own expiry unless their session is revoked; apps must call online session validation to observe immediate revocation.
Native clients may list/revoke their own app/environment sessions at /api/auth/sessions?client_id=your-app-id using Bearer authorization. Cookie and bearer contexts cannot be mixed. Sign out everywhere across apps requires the Auth account interface and recent authentication. An older unscoped native session must sign in again before using the list.
Helpers are source downloads; installing an older published SDK does not add this feature. Integrate and test storage, single-flight refresh, cancellation, relaunch, expiry, sign-out and reauthentication in your app. A successful refresh does not mark a login-method connection test Verified. Direct native iOS passkey sheets and device biometric unlock remain separate capabilities.
Connection testing
Open your app’s Login settings, save the chosen method, then select the exact environment, return URL and platform. Every app uses the same catalog. On means allowed; it does not mean connected.
Off, Setup required, Ready to test, Testing, Verified and Test failed are separate states. A real test must sign in with the selected method, return to your app, obtain a valid Auth session and acknowledge that specific session using a proof your app generated before sign-in. A callback URL check, a token inspection or a checkbox never grants Verified.
- Register the complete callback for the environment. iOS needs the URL scheme or associated domain in the app target; other native platforms need their supported app-link handler. Native clients use S256 PKCE without an app secret.
- Download the matching developer-only helper and include it in your test build. Existing published SDK versions may not include this helper yet. Keep it out of normal user flows.
- Click Test connection in App Login. Copy its temporary ticket into your app’s developer test screen. Tickets expire after 15 minutes; keep them out of URLs, logs and source control.
- Before starting authentication, attach the ticket from your app with its expected method, environment and exact callback. Native clients also supply the same PKCE challenge, state and nonce they will use for sign-in. Keep the receipt in memory; web apps can preserve its short-lived proof in same-origin session storage across the callback.
- Perform the real sign-in. Validate callback state, redeem the one-time native code with the original verifier and validate/store the session through your normal integration. The older hosted web flow returns a token; validate and accept that session before acknowledgment.
- Call the receipt’s acknowledge method with that session token. Auth checks the original app proof and the server-correlated live session before setting Verified. Report cancellation or callback/exchange/session errors through the receipt’s failure method. Refresh settings to see the result and successful test time.
Swift uses AelithConnectionTestReceipt.attach and acknowledge(sessionToken:). JavaScript uses ConnectionTestReceipt.attach and acknowledge(token). Web apps launch through receipt.launchHosted(sessionStorage, document); the launch secret is POSTed, not placed in a URL. On the same-origin callback use ConnectionTestReceipt.restore before acknowledgment. These helpers do not replace normal login, PKCE or session validation.
Apple’s native iOS sheet also requires the correct Apple App ID capability and Auth audience. Apple/Google/GitHub operator credentials stay on Auth’s server. Email includes Create account and verification; an existing-user test does not verify signup email delivery. Wallet support varies by platform; this test never requires a funds transfer. Native GitHub remains unavailable until its secure bridge is implemented.
Changing app/environment configuration or the Auth deployment invalidates current verification. Verified proves the tested integration round trip at its recorded time; it is not binary/device attestation and does not certify every login variant, device, or future session. It neither signs users out nor changes their permissions. An expired/cancelled test grants nothing.
Set up passkeys and password recovery
Start with the role that applies to you. Auth’s operator activates the platform features; app developers choose methods and integrate their app; individual users enroll their own passkeys. A saved switch alone does not complete any of these steps.
1. Auth operators · activate the platform
If you are building an app on hosted Aelith AUTH, skip to the developer steps below. You do not need access to Aelith’s Vercel project, SMTP credentials or database. Contact the Auth operator if a feature shows Setup required.
- For Aelith’s operator, open the
auth-aelithVercel project → Settings → Environment Variables → Production. The recovery/passkey schema has already shipped on hosted Aelith AUTH; do not rerun its migration. Self-hosted operators must apply their release’s reviewed migration before activation. - Set the feature flags below and verify the exact trusted origin.
AUTH_PASSKEY_RP_IDis optional: it defaults to the origin’s hostname and, when supplied, must match that hostname exactly. Use your own trusted HTTPS origin for a separate installation. - Recovery reuses Auth’s existing SMTP delivery. Confirm
SMTP_HOST,SMTP_PORT,SMTP_USER,SMTP_PASSandSMTP_FROMas required by your mail provider. Keep credentials in protected server configuration; never copy them into app code or Docs. Existing signup-code delivery is useful evidence, but reset delivery still needs a controlled test. - Redeploy Production after saving environment changes. Check
/api/auth/providers:passkeyreflects the feature flag plus valid origin/RP configuration;passwordRecoveryreports the recovery flag only, not SMTP delivery. Neither response proves a completed sign-in or password reset. The flags are operator configuration, not switches in the Auth dashboard. Turn a flag off and redeploy to disable that feature again.
Operator-only Production configuration · hosted Aelith AUTH
PASSKEYS_ENABLED=true
PASSWORD_RECOVERY_ENABLED=true
NEXT_PUBLIC_APP_URL=https://auth.aelith.ai
# Optional; defaults to the hostname above:
AUTH_PASSKEY_RP_ID=auth.aelith.aiPasskeys require no new Apple or Google OAuth client. They use Auth’s relying-party domain and supported WebAuthn authenticators. Recovery needs working email delivery; setting its flag alone cannot confirm SMTP delivery.
2. App developers · configure and integrate
- Open your app → App Login → Choose how users sign in. Enable Passkey and click Save login methods. Email controls email sign-in, signup and recovery together; there is no separate per-app Forgot password switch. Keep at least one usable method. Changes do not sign out existing sessions.
- Save your exact environment callback and consume authoritative capabilities. For native clients use
/api/oauth/methods?client_id=your-app-id&platform=ios;passkeyandpassword_recoveryreflect the saved app choices plus platform readiness. Do not assume a button is available after a failed or stale capability request. - Hosted login displays available methods and the recovery link. Custom email forms must add their own recovery UI; native clients can use the cookie-free recovery endpoints and Swift helper. Native passkeys use
provider=passkeythrough the system-browser S256 PKCE flow, then validate state, redeem the code and accept the session. A toggle does not update an installed app automatically. - Run a method-specific connection test with the helper in your app. Verified requires the real round trip and acknowledgment of the accepted session. Passkey enrollment, a successful browser prompt or an On switch alone does not verify the app. Password recovery has no separate connection-test badge; test its delivery/reset/relogin journey on an authorized test account.
Direct native iOS passkey sheets are not implemented in this integration. Do not add associated domains or a Face ID button expecting this browser bridge to supply a native ceremony. See passkey support and security limits.
3. Users · enroll a passkey or recover a password
After platform activation, sign in to Auth with an existing supported method, then open Account security within five minutes of signing in. Choose Add a passkey and complete your device’s prompt. Keep another usable sign-in or recovery method. Your device may use Face ID, Touch ID, a screen lock or a security key; no particular biometric prompt is guaranteed and Auth does not receive biometric data.
For a forgotten email password, choose Forgot password. Only an existing verified password account can reset; social-only accounts must use their original method. The generic response does not confirm an account exists or a message was delivered. Use the one-time link within 15 minutes, set a new password, return to your app and sign in again. Existing Auth sessions are invalidated; a reset does not sign you in automatically.
Passkey enrollment currently requires a recent Auth web session; a native app session alone is not an enrollment bridge. Apple remains excluded from Auth’s own portal login, so native-first Apple users need another supported Auth web sign-in before enrollment.
Check setup and troubleshoot
- Passkey shows Setup or cannot be enabled
- Ask the operator to check the flag, exact HTTPS origin/RP and completed redeployment. App developers cannot activate the global feature from an app’s settings.
- Passkey is on but no button appears
- Save settings, refresh capabilities and reopen the sign-in screen. A custom app must implement the supported flow. Confirm a secure supported browser; direct native sheets are not supplied.
- No passkey found or enrollment asks you to sign in again
- Enroll a credential for Auth’s domain, or sign in using another method. For enrollment/removal, establish a fresh supported Auth web session rather than relying only on a native token.
- Forgot password is missing or no email arrives
- Check saved Email availability, the recovery flag, redeployment and custom-client UI. Check spam and operator mail delivery. Unknown, unverified and social-only accounts receive the same response without a reset email. Respect retry limits; do not share reset links in logs or screenshots.
- Reset link expired, was used, or the prompt was cancelled
- Request a fresh reset link or start a fresh passkey sign-in. Never reuse a code, challenge or PKCE binding. No success should be assumed after cancellation.
Before rollout, use authorized test accounts to verify real email delivery and recovery/relogin, plus real-device enrollment, sign-in, cancellation and removal. Automated fixtures do not prove mail delivery or Face ID/device behavior. Do not label a method Verified until the app’s actual connection test completes.
Password recovery
Email login includes Forgot password when the operator has activated recovery. Requests always return the same response for known, unknown, unverified and social-only addresses. Only an existing verified password account can reset; this never adds a password to a social identity.
Reset links expire after 15 minutes and work once. The token is carried in the URL fragment, removed from browser history when the reset form loads, and sent only in the reset POST body. Never put a reset link in analytics, logs or support screenshots. A reset does not sign the user in automatically.
A completed reset invalidates existing Auth portal cookies, hosted/native sessions, outstanding reset links and older native-code/password-verification attempts. Linked sign-in methods remain linked. Apps checking JWTs entirely offline must use hosted or native session validation to observe immediate revocation; a local signature check alone cannot query recovery state.
For native email forms, use the cookie-free JSON endpoints /api/oauth/recovery/request with appId and email, and /api/oauth/recovery/reset with appId, token and password. Do not send cookies, Origin or browser fetch headers. The normal browser form uses same-origin /api/auth/recovery/request and /reset. Recovery accepts no custom redirect parameter; return to the app and start a fresh login.
The Swift helper uses an ephemeral cookie-free session and rejects redirects. It requests recovery or changes a password with the supplied token; it never stores the token or creates a login session. Existing apps must add their own recovery UI. Auth does not modify installed apps automatically.
Passkeys · device-based sign-in
Passkeys use a public-key credential scoped to Auth’s exact configured relying-party domain. A supported device may use Face ID, Touch ID, Windows Hello, its screen lock or a security key. Biometric data stays on the device; Auth verifies the signature and required user-verification flag.
Follow Passkeys & recovery setup for operator activation, app settings, enrollment and testing. The sections below describe the security and native-platform boundaries.
Direct native iOS passkey sheets are not implemented by this browser integration. They additionally require your app’s associated webcredentials domain, Auth’s approved Apple app-site association and a native SDK ceremony bridge. Do not claim that setup exists or add a native Face ID button without that integration. The browser path does not need those app entitlements. Passkey enrollment currently requires a recent Auth web session; a native app session alone is not an enrollment bridge. Native-first users must first establish that supported web session.
Auth requires discoverable credentials and user verification; challenges expire in five minutes, are bound to the browser/app/callback and work once. Sign-in discovers a saved credential without exposing an email lookup. Removing a passkey revokes existing Auth sessions; removing the last usable method is blocked. Deleting a passkey in Auth does not delete its copy from the user’s password manager.
Troubleshooting
- Setup required
- Save an exact environment callback, check provider availability and platform support, then follow the selected method’s guide. Native GitHub cannot be enabled by configuration.
- Testing · waiting for app acknowledgment
- A token was issued, but your app has not completed its helper acknowledgment. Match the original method, environment, callback, PKCE binding and accepted session. Token minting alone is not Verified.
- Callback, exchange or expired-test errors
- Check exact URI registration, state, original verifier, code expiry and callback handling. Cancelled or expired tests grant nothing. Start a fresh test after correcting the cause.
- 401 or 429
- 401 means the key, token or session was not accepted. 429 means an operational rate limit or workspace allowance was reached. Respect retry guidance; repeatedly retrying a monthly-limit response will not reset it.
Dashboard diagnostics inspect callback configuration and tokens; they never mark a method Verified. Test existing-user login and new-account email delivery separately when both matter to your app.
Successful hosted verification usage is shared across owned apps. Per-app attempt limits use UTC minutes; monthly counters reset on the first of the month UTC. Users and verifications are different metrics. Compare plans.