The practical answer
Passwordless web authentication should reconnect a returning user with their saved work without confusing that work with the current session. Gammal Tech provides hosted sign-in and per-user project storage. Your app should confirm sign-in, load the saved record, enable editing, confirm saves and clear the account view at sign-out.
A customer finishes lesson three on a laptop, signs out and later opens your website on a phone. They expect lesson four to be ready. That continuity comes from the record saved for their account in your project, even though the new login has a different temporary token.
This guide focuses on that lifecycle and the data mistakes that can break it. For method names and integration checks, use the passwordless authentication API integration guide. If you are still choosing the customer account model, begin with the website login decision guide.
Separate the account, the session and the saved record
For this integration, passwordless means your website does not collect or store a separate application password. The customer completes Gammal Tech account sign-in in a hosted popup. Your app receives a session credential, which remains sensitive.
| Part | Purpose | What your app should assume |
|---|---|---|
| Account | Represents the person who signs in. | The same account can return across visits and devices. |
| Session token | Supports the current authenticated interaction. | A new random token arrives with each login. It is not a permanent customer number. |
| Saved project data | Stores the preferences and progress your project saved for that account. | It can survive sign-out and be loaded after another successful sign-in. |
Do not use an old token as a database key to reconnect a customer with progress. The user-data service maintains the association with the account. Your project can retrieve the data it previously stored for that user; it cannot retrieve data belonging to another developer's project or look up the person's underlying Gammal Tech identity.
Design the session lifecycle as visible states
Authentication is asynchronous. A clicked button, an opened popup and a completed login are different events. Show a clear state while each operation is pending, and enable actions only when their prerequisites have succeeded.
| State | What the visitor sees | Application behavior |
|---|---|---|
| Checking | “Checking your session…” | Keep account-specific content hidden while deciding which view to show. |
| Signed out | A clear Sign in control. | Allow public reading; keep account-dependent saves unavailable. |
| Signing in | “Complete sign-in in the popup.” | Prevent duplicate login attempts and handle an incomplete flow. |
| Loading data | “Loading your saved progress…” | Read the record before enabling edits that could overwrite it. |
| Ready or saving | Current content and an honest save status. | Confirm completion before saying that work is saved. |
| Unavailable | A brief recovery instruction. | Keep unconfirmed changes distinct from saved data and offer a deliberate retry. |
The documented GammalTech.onAuth(onIn, onOut) helper runs the matching callback when called. Use the documented session check where current validity matters. Do not assume onAuth is a continuous subscription to every future change or that a previously painted “signed in” badge proves a session remains valid.
Closing or blocking the popup is not successful authentication. Keep the previous safe view, restore the sign-in control and explain that sign-in was not completed. A network failure also does not prove that the customer deliberately signed out; it means the current operation could not be confirmed.
Restore saved data before writing defaults
The most damaging returning-visit bug is easy to create: initialize the screen with an empty reading list, then automatically save that empty list before the existing record has loaded. Authentication can work perfectly while the app still replaces the customer's useful data.
- Complete or confirm sign-in. The user-data methods require a logged-in user.
- Read with
GammalTech.user.get(). An empty object is the documented result when no data has been saved; a failed request is a different outcome. - Validate the fields you use. Check types and allowed values. Treat a missing optional preference as a reason to display a default, not to erase unrelated fields.
- Enable editing after restoration. If loading failed, explain that saved work is unavailable and avoid writing a fresh default record over it.
- Save the intended change. Confirm the operation before showing “Saved.”
For example, restore a language choice and the last completed lesson before the learner continues. A display default of English can be reasonable when language is absent. It should not silently replace a stored Arabic preference because a request was slow.
Use an app-defined data version if the record format will evolve. Read older versions carefully and migrate only the fields you understand. That version describes your stored format; it is not a server locking or conflict-detection feature.
Top-level updates preserve keys; nested objects are replaced
The documented save operation merges at the top level. Keys you omit stay in the record. If a key contains an object and you send that key again, the entire nested object is replaced. This distinction determines whether a settings update preserves progress.
{
"language": "en",
"progress": { "lesson": 3, "completed": [1, 2, 3] }
}Saving only { "language": "ar" } changes the language and preserves the top-level progress value. Saving { "progress": { "lesson": 4 } } replaces the whole progress object, so the omitted completed list is no longer part of that object.
If both nested fields must survive, load the existing value, validate the fields you intend to keep and send the complete replacement object. A read followed by a save is still two operations; it does not provide a transaction against concurrent changes.
Keep each user's record within the 1 MB maximum. Keys beginning with _gt_ are reserved and rejected. The guide does not define a generic top-level delete method, so plan removal within your own saved structure instead of inventing an SDK operation.
Preferences, bookmarks, compact learning progress, settings and small drafts fit this model. A file archive, unbounded activity history or shared company database needs a separate design. Free storage does not mean unlimited data size.
Prevent old requests from repainting a new session
Consider a slow progress request. The customer signs out while it is still pending; the response then arrives and paints their old account information back onto the screen. Clearing the interface once is insufficient if later callbacks can restore it.
Track which sign-in state started each request and discard its result if that state is no longer current. An application can use an in-memory generation counter for this purpose, advancing it on sign-out and when beginning a new account view. This is a UI correctness technique, not a replacement for service-side session validation.
Also prevent overlapping saves within one editor. Disable or queue the next save until the pending operation settles. The SDK already retries brief network problems, so do not wrap its calls in endless retry loops that make it harder to tell which change completed.
Across devices, the same customer can independently edit an older copy of a record in more than one place. The published storage contract does not promise atomic increments, revision checks or automatic conflict resolution. For a high-value shared edit, choose a workflow with the needed concurrency guarantees. For a personal preference, a clear single-editor workflow and reload before a subsequent edit may be sufficient.
Explain tab sessions without promising global sign-out
Gammal Tech documents the session as kept per browser tab, with sign-in required in a fresh tab or after reopening the browser. Persistent project data is separate: once the same account signs in on another device, your project can retrieve its previously saved record.
Treat the per-tab description as the supported user journey, not a guarantee about every browser restoration action. Browser session storage can survive reloads and restoration, and a page with an opener can initially receive a copy of that opener's storage. Check actual session validity rather than making a security decision from whether a tab appears new.
On sign-out, call the documented logout method and clear your app's account view, in-memory record and pending rendering work. If the request fails, remove private content from the visible screen but avoid claiming that remote invalidation succeeded. Keep a clear way to retry.
Local sign-out does not establish that every device or browser has been signed out. Do not add an “all devices” promise without a documented capability that implements it. Registering several project domains also does not establish automatic cross-domain or cross-tab login continuity.
Restore useful information without exposing credentials
Session verification does not return the account holder's name, email, phone number, National ID number or identity documents to the developer. That privacy boundary does not make the person anonymous to Gammal Tech. Your app can separately ask the customer for information needed for its own service, but such a form is your own collection, and the supplied answer is not automatically verified by login.
Validate restored fields before using them. For ordinary visible text, put the validated value into a normal text element with textContent; do not turn a saved nickname or draft into HTML. A saved value is still input, even when it came back from storage.
Keep tokens out of analytics events, public messages, URLs you create, screenshots and routine diagnostics. Let the SDK manage its session instead of copying the token into long-lived browser storage to manufacture a “remember me” feature.
A stored preference must not grant administrative access or prove a purchase. Those decisions have their own trusted controls, described in designing a website authentication system. Existing customer records also need a deliberate account-linking plan; migration is not automatic.
Check the whole returning-visit experience
- Save a fictional language preference and progress value, sign out, then sign in with the same account and confirm both return.
- Repeat on a second device and distinguish restored data from a reused token.
- Delay or fail the initial data load; confirm that empty defaults are not automatically saved.
- Update one top-level field and then a nested object; verify the intended preservation and replacement behavior.
- Sign out during a pending read; confirm a late response cannot restore the private account view.
- Try an interrupted login and a failed save; confirm the interface never reports uncompleted work as successful.
Use accounts and projects you are authorized to test and non-sensitive example data. Each tester should use their own account; the one-account-per-person model does not call for duplicate personal accounts.
Setup and costs supporting this lifecycle
The project owner needs a verified account and registered HTTPS domains. A project supports up to four domains; bare and www domains count separately. The project ID is public configuration, and no secret developer API key is required. Current identity requirements use a National ID from a country of citizenship; the limited Egyptian document exceptions are listed in the official account setup reference.
Login, logout and session checks are free with unlimited use. User storage is also free within the 1 MB per-user limit. Each project includes 200 OTP codes per month for login and checkout identity verification, then charges 0.40 EGP per additional code (approximately US$0.0077 at the historical reference rate below). The allowance resets monthly.
Fund the personal wallet and transfer funds to the project balance for paid usage. The first project is free; additional projects have a one-time fee shown in the Console. For a budgeting comparison, see authentication code pricing.
Currency guide: EGP amounts are the billing prices. The approximate USD figure uses USD 1 = EGP 51.78, the calculated midpoint of Banque Misr's buying and selling rates on 24 September 2026, retained from the original article. It is not a current exchange-rate quote; payment-provider rates and fees may differ.
Questions about passwordless sessions and saved work
Does signing out delete the user's saved preferences?
No. Sign-out clears the local session. Data your project has saved for the account can be retrieved after another successful sign-in. Unsaved edits are different and need their own clear status.
Why does a new login token still lead to the same progress?
The service ties project storage to the account, while the token represents a temporary session. Your app does not need to reuse an old token or obtain the customer's email to restore its own saved data.
Can a failed data request be treated as a first visit?
No. A successful read returning an empty object means no data was stored. A failed read means you do not know what is stored. Avoid saving defaults until that distinction is resolved.
Does passwordless mean there is no credential to protect?
No. It removes the separate application password for this flow. The session credential, saved inputs and your product's permission decisions still need appropriate protection.
References
Platform contract checked 14 October 2026. The state model, examples and release checks above are implementation guidance based on that contract.
- Gammal Tech integration reference: sessions, user storage, top-level merging, limits, project setup and pricing.
- MDN: sessionStorage: browser tab, opener and restoration behavior.
- MDN: textContent: writing ordinary text without parsing it as HTML.
- OWASP: session management and HTML5 security: protecting session identifiers and browser storage.