> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Session sync

> Keep single-use sign-in tokens in step across tests and crawls that resume the same login

## What it is

Some apps sign you in with a token that can be used only once. Each time the app refreshes your session, it swaps the old token for a new one and the old one stops working. When several tests or crawl branches resume from the same saved login, the first one to refresh uses up the token, and the rest are signed out.

Session sync keeps those tokens in step. You list which cookies or storage keys hold the token. When any browser in a run or crawl gets a new value, QA.tech passes it to the other browsers resuming from that same login. They only ever use the newest token. Other cookies and storage are never shared.

> [!NOTE]
>
> Session sync is available for web applications. Mobile and API applications
> show the setting, and it stays off.

## When you need it

Turn it on when resumed sessions lose a login that the first test, or a sibling crawl branch, still has:

* Tests that depend on a login pass on their own, and get signed out when they run together.
* A crawl that starts from a saved login sends some branches back to the sign-in page.
* The app uses a single-use refresh token, such as WorkOS AuthKit, Auth0, Okta, or a custom cookie that changes on every refresh.

| What you see | What to change |
| :- | :- |
| Every test that resumes the login is signed out, including the first one, and the saved login is older than its [Session State Lifetime](https://docs.qa.tech/core-concepts/session-state-lifetime.md) | The session expired. Shorten the lifetime, or run the login again. Session sync does not extend an expired token. |
| The first test or crawl branch stays signed in, and the ones that resume the same login are signed out | The token was used once. List that key under Session sync. |

## How it works

**1. Resume a saved login**

A test or crawl branch opens the browser state saved by a login it resumes
from.

**2. Share the newest value**

When any of those browsers receives a new value for a listed key, the others
resuming that same login receive it too. They only use the newest value.

**3. Take turns refreshing**

Refreshes of the same token happen one at a time, so two browsers do not
spend the same single-use token.

Session sync is per application, for web applications only, and only for the keys you list. A test with no Resume From dependency starts from a fresh browser and does not join the sync.

## How to configure

**1. Open the application**

Go to **Settings → Applications & Envs**, then select the application.

**2. Edit Session sync**

Open **Session sync** and click **Edit**. Add the token key, or use
**Refresh cookie** or **WorkOS AuthKit** when those match your app.

**3. Save**

Click **Save**. The change applies to new runs and crawls.

| Type | Example pattern | Matches |
| :- | :- | :- |
| Cookie | `refresh-token` | A cookie with that exact name |
| localStorage | `workos:refresh-token*` | Keys that start with `workos:refresh-token` |
| sessionStorage | `auth.refresh*` | Keys that start with `auth.refresh` |

`*` matches any ending. List the token key only, not the whole session.

> [!TIP]
>
> You can also ask the assistant: "my tests get logged out after the login
> test". It can look at the saved login and add the token key after you agree.

## Finding the right key

Open the app in a browser, sign in, and open DevTools on the Application tab.

1. Watch Cookies, local storage, and session storage while you refresh the page.
2. The token key is the one whose value changes after each refresh.
3. Add that name. If several keys share a prefix, use a `*` pattern. Leave every other key off the list.

## Notes

* Values are never shown in Settings or in chat. You only see key names.
* A change applies to new runs and crawls. It does not rewrite a run that is already going.
* Clearing the list turns session sync off.
* Run the login again after you enable it. Sessions saved before that keep the token they stored, and they do not share later refreshes until that login runs again.

| Situation | What happens |
| :- | :- |
| A test logs out, or the application allows one session per user | The application revokes the token on its server. Other tests cannot stay logged in after that. Give logout tests their own login, or order them with Wait For so they do not run beside tests that still need the session. |
| A test switches accounts by overwriting the token, without logging out first | Treated as a normal refresh. Other tests on that login receive the new account's token. |
| A test logs out and then logs in again | The new login stands on its own. Tests still on the previous login do not receive the new token. |
| The token lives in IndexedDB, or only in the page's memory | Not synced. Cookies, local storage, and session storage are. |
| A guest token and a signed-in token share a name | Configure the signed-in token. A guest token that matches the same name is synced too, and can replace the signed-in value. |
| A session you selected by hand is older than 8 days | Uses the token saved in that session. Newer refreshes are kept for 8 days, one day longer than the longest [Session State Lifetime](https://docs.qa.tech/core-concepts/session-state-lifetime.md). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.