Sessions

In short

After you sign in, SpeculaPro gives your browser a session, a temporary pass that saves you from signing in again on every click. The pass is a long random value in a browser cookie. The server keeps a record of every pass it has issued, so it can cancel any pass at any time.

A session ends when:

you sign out,
you have been inactive for a while (30 minutes by default), or
it reaches its maximum lifetime (12 hours by default), however active you are,
you change your password from another session (every other session is signed out),
you remove a passkey: the other sessions that passkey opened are signed out (see Passkeys), or
an administrator disables your account, resets your two-factor or issues you a temporary password. All your sessions end at once; see Managing people.
your workspace starts requiring single sign-on and your session was started with a password (unless you are a break-glass administrator). See Requiring SSO.

Lifetime settings

Setting	Default	Meaning	Configured with
Maximum lifetime	12 hours	A session never lasts longer than this, even with constant use	`SP_SECURITY_SESSION_TTL`
Idle timeout	30 minutes	A session with no activity for this long ends	`SP_SECURITY_SESSION_IDLE`

The defaults suit an eight-hour working day with breaks: you sign in once in the morning, and an unattended screen locks itself out after half an hour.

How sessions are protected

Protection	In plain words
Server-side sessions	The session lives on the server. Signing out, or an administrator disabling your account, ends it immediately.
Random token, stored only as a fingerprint	The cookie holds a long random value. The database stores only its SHA-256 fingerprint, so a copy of the database contains no usable session tokens.
HttpOnly cookie	Scripts running in the page can’t read the cookie, which blunts a whole class of attacks (cross-site scripting).
Secure cookie	The cookie is only sent over HTTPS.
`__Host-` cookie name	The cookie is called `__Host-sp_session`. Browsers only accept a cookie with that prefix over HTTPS, for the exact host that set it, so a neighbouring subdomain can’t plant or overwrite it.
SameSite=Strict	The browser doesn’t send the cookie with requests started from other websites, which blocks cross-site request forgery.
Origin check on every change	As a second guard, the server refuses any request that changes something unless it comes from SpeculaPro’s own address. See Requests that change something below.
MFA recorded on the session	Each session records whether the second factor was verified. A session without it can only finish setting up MFA or changing the password.
Device details	The IP address and browser of each session are recorded, to help spot sessions you don’t recognise.
How it started	Each session records whether it began with a password (`password`), a passkey (`passkey`) or through single sign-on (`sso_oidc`, `sso_saml`). A passkey session counts as two-factor from the start, because the device checked the person. The `auth.login` entry in the audit log records the same, with the identity provider’s identifier for the person.

Requests that change something

A website you visit in another tab must not be able to make your browser save, delete or approve something in SpeculaPro on your behalf. That attack is called cross-site request forgery. The cookie’s SameSite=Strict setting already stops the browser sending the cookie in that situation. The server also checks for itself, on every request that changes something (POST, PUT, PATCH, DELETE), signing in included:

The request…	Answer
Says it comes from another site (the browser’s `Sec-Fetch-Site` header is anything but `same-origin` or `none`, or its `Origin` header names another host)	`403` cross-site request rejected
Uses a session cookie but carries neither `Origin` nor `Sec-Fetch-Site`, so the server can’t tell where it came from	`403` a signed-in request that changes something must carry an Origin or Sec-Fetch-Site header: browsers add one; a script must send Origin with this site’s own address
Comes from SpeculaPro’s own address	Carried out

Browsers add these headers by themselves, so people using the web app never notice. Only a script that signs in and reuses the cookie has to add Origin itself; see Authentication. Requests made with an API key carry no cookie, can’t be forged this way, and are not checked.

The web app is served by the same program as the API, from the same address. That is what lets SpeculaPro use a strict, simple cookie, without opening up cross-site access. See Design decisions.

Sessions after single sign-on

A sign-in through your identity provider gets exactly the same SpeculaPro session, with the same cookie, lifetime and idle timeout. The identity provider’s own session is separate: signing out of SpeculaPro doesn’t sign you out of your other work applications, except that after an OpenID Connect sign-in SpeculaPro also sends you to the identity provider’s sign-out page, if it has one. Disabling someone at the identity provider stops new sign-ins, but a SpeculaPro session they already have runs until it ends; disable them in SpeculaPro too. See Single sign-on security.

Support sessions are a different thing

On the hosted service, a member of SpeculaPro’s staff whom your workspace has approved looks inside it through a support session. It is not a person’s session: it has its own cookie (__Host-sp_support), belongs to no user, is read-only, is limited to the scope you approved, ends with the approval, and is checked against that approval on every request with no cache. Suspending a workspace ends every person’s session and every support session in it. See Support access security.

Machines don’t use sessions

Integrations (your payment system sending transactions, a scheduled job sending batches through the ingest API) use API keys, not sessions. The one file upload done with a session is an administrator importing a file by hand under Settings → Data import; see Importing a file.