Session Security & Management

Understanding how Flowsta manages your authentication sessions and keeps your account secure.

The Three-Token Model

Flowsta uses three types of tokens with different lifetimes:

Token	Lifetime	Purpose
Access token	24 hours	Authorizes API requests from OAuth apps
SSO session cookie (flowsta_session)	7 days	Keeps you signed in across Flowsta sites
Refresh token	30 days	Silently obtains new access tokens

How they work together:

• When you sign in, Flowsta sets the SSO session cookie - a 7-day JWT scoped to .flowsta.com. While it's valid, Flowsta sites and "Sign in with Flowsta" consent screens recognize you instantly.
• When an OAuth app completes the flow, it receives an access token (24 hours) and a refresh token (30 days).
• When the access token expires, the app exchanges the refresh token for a new access token. The refresh token itself is not rotated - it keeps its original 30-day expiration from the time of issue.
• After the refresh token expires, the app sends you through the sign-in flow again.

How You Sign In

There is no password. Signing in is a cryptographic challenge your device answers:

1. Flowsta Vault requests a one-time challenge (POST /auth/vault/challenge)
2. The Vault signs it with your device key - derived from your 24-word recovery phrase, never sent anywhere
3. The signed challenge is exchanged for a session (POST /auth/vault/token), which returns a JWT and sets the flowsta_session cookie

If you lose every signed-in device, your recovery phrase restores your identity in Flowsta Vault on any device - then you sign in as normal. See Zero-Knowledge Architecture for the full picture.

What Happens When Sessions Expire

When your session expires:

1. Automatic sign-out - you're signed out to protect your account
2. Clear message - you'll see an explanation that your session expired
3. Easy return - after signing back in, you'll return to the page you were viewing

Session Types

Website Sessions (OAuth/SSO)

When you sign in to a partner site using "Sign in with Flowsta":

• Duration: 7 days per site
• Independent: each site has its own session
• Seamless: while your Flowsta SSO cookie is valid, other sites recognize you instantly
• Secure: sessions stored in HTTP-only cookies (protected from JavaScript access)

Direct Sessions

When you sign in directly to your Flowsta dashboard:

• Duration: 7 days
• Persistent: remains active across browser tabs
• Secure: JWT with a cryptographic signature

Multiple Devices

You can be signed in on multiple devices simultaneously. Each device has its own independent 7-day session.

Session Security Features

Protection	Description
HTTP-only cookies	Session tokens can't be accessed by malicious JavaScript (XSS)
Secure flag	Cookies transmitted only over HTTPS
SameSite=Lax	Blocks cross-site request forgery (CSRF)
Token expiration	Limits the damage window if a token is compromised
Log out on all devices	One-click option to end all sessions everywhere
Vault approval	Every sign-in is approved by you, in your Vault, on your device

Managing Your Sessions

View Active Sessions

1. Go to Dashboard → Settings → Security
2. View the list of active sessions with device and last-active time

End Specific Sessions

1. Find the session in your Active Sessions list
2. Click Revoke next to that session
3. That device is signed out immediately

Log Out Everywhere

1. Go to Dashboard → Settings → Security
2. Click Log Out on All Devices

When to use this: lost device, suspected unauthorized access, or after using a public or shared computer.

Best Practices

For Users

1. Sign out on shared computers - public library, internet café, someone else's laptop
2. Review active sessions regularly - revoke unfamiliar devices and sessions from devices you no longer use
3. Keep your recovery phrase safe - it restores your identity on any device if you lose access to all of them
4. Lock your Vault when you step away - sign-in approvals happen there, so its password is your extra check

For Developers

If you're building an app that uses Flowsta authentication:

1. Handle expired sessions gracefully

   • Detect 401 responses
   • Show a friendly "Session expired" message
   • Redirect to sign-in with a return URL

2. Implement token refresh

   • Check token expiration before requests
   • Refresh proactively (before expiration)
   • Handle refresh failures gracefully - after 30 days the refresh token itself expires and the user must sign in again

3. Store tokens securely

   • Use HTTP-only cookies for server-rendered apps (best)
   • The @flowsta/auth SDK uses localStorage for SPA convenience (acceptable for PKCE flows without client secrets)
   • Sensitive PKCE data is stored in sessionStorage and cleared after use

See the SDK Documentation for implementation details.

FAQ

Why do I get signed out after 7 days?

Security. Short-lived sessions reduce the risk if someone gains access to your device or if a session token is compromised.

Can I stay signed in longer?

The 7-day SSO limit is a security measure and cannot be extended. Apps can use refresh tokens to keep API access alive for up to 30 days without re-prompting you.

I was signed out before 7 days. Why?

Possible reasons: you manually signed out, you used "Log Out on All Devices", your browser cleared cookies/storage, a security measure triggered, or (rarely) server maintenance.

What if I lose access to my session?

Just sign in again from Flowsta Vault. If you've lost the device entirely, restore your identity on a new device with your 24-word recovery phrase, then sign in as normal.

Are my sessions encrypted?

Yes. Sessions use JWTs with cryptographic signatures, HTTPS encryption in transit, and HTTP-only cookies that JavaScript can't read.

Can someone steal my session?

While no system is 100% secure, Flowsta uses industry-standard protections: short-lived tokens, secure HTTP-only cookies, HTTPS-only transmission, and strict expiration enforcement. There is no password to phish - sign-in requires a signature from your device key, approved by you in your Vault.

Privacy & Data

What a Session Contains

• User ID
• Holochain agent public key and DID
• Expiration timestamp

Not stored: any password (none exists), private user data, browsing history. For device-hosted accounts the session doesn't even contain your email - the server only ever held a hash of it.

Zero-Knowledge Architecture

Your session proves who you are; it doesn't unlock your data:

Your 24-Word Recovery Phrase
    ↓  HMAC-SHA256 (on your device)
Your Ed25519 Device Keys
    ↓
Sign-In = Challenge Signature          Private Records = Sealed on Your Device
    ↓                                       ↓
Flowsta Verifies Your Public Key       Never Sent to Flowsta ✓

Even if someone obtains a session token, they cannot access your recovery phrase, your device keys, or your sealed private records - none of those ever leave your device. They can only access what that session is authorized to access, until it expires or you revoke it.

Technical Details

For developers implementing Flowsta authentication:

JWT Structure

A session JWT for a device-hosted account:

{
  "id": "user_abc123",
  "userId": "user_abc123",
  "email": null,
  "agentPubKey": "uhCAk...",
  "did": "did:key:z6Mk...",
  "hostingModel": "device-hosted",
  "iat": 1698765432,
  "exp": 1699370232,
  "iss": "flowsta-auth",
  "aud": "flowsta-sites"
}

Token Claims

Claim	Description
id / userId	Unique user identifier
email	null for device-hosted accounts - the server holds only an email hash
agentPubKey	Holochain identity (public key)
did	W3C Decentralized Identifier
hostingModel	Account hosting model
iat	Issued at (timestamp)
exp	Expires at (timestamp, +7 days)
iss	Issuer (flowsta-auth)
aud	Audience (flowsta-sites)

Session Cookie

Set-Cookie: flowsta_session=eyJhbGc...;
  HttpOnly;
  Secure;
  SameSite=Lax;
  Max-Age=604800;
  Domain=.flowsta.com

See the API Reference for complete technical documentation.

Related Documentation

• Getting Started Guide
• OAuth Integration
• API Reference
• SDK Documentation

Need Help?

• Discord: Join our community
• Support: Find out about Flowsta support options
• GitHub: github.com/WeAreFlowsta

---

Last Updated: July 2026