Account security
Everything here lives on Account → Security in the dashboard.
Sign-in methods
You can sign in with an email and password, and with Google, GitHub or Microsoft when the server has them configured. An organization can also have its own SSO connection (OIDC or SAML), set up by the operator.
A provider sign-in with an address that already has a TheSpider account joins that account only when both sides have verified the address. Otherwise the login page says the account exists but is not linked:
- If the account is yours, sign in with its password and use Link Google / GitHub / Microsoft on Account → Security.
- If you never created it, or do not know its password, reset the password. The reset email proves you own the mailbox and signs out every other session. Then link the provider.
Verifying the email address alone is not enough to take an account back: it keeps the existing password and sessions.
You cannot unlink your last sign-in method, or the last one that an organization you belong to
requires (last_compliant_method).
Two-factor authentication
Add a second factor to every sign-in:
| Factor | Notes |
|---|---|
| Passkey | Touch ID, Windows Hello, a phone or a security key. Needs HTTPS (or localhost); on a plain-HTTP server the dashboard offers only the authenticator app. |
| Authenticator app | Any TOTP app (6 digits, 30 seconds). Scan the QR code or type the secret. |
| Recovery codes | Ten single-use codes, issued when you add your first factor. Store them somewhere safe. Generating new codes invalidates the old ones. |
After a password, Google, GitHub, Microsoft, SSO or email-link sign-in, an enrolled account must
verify a factor within 15 minutes. Until then the session can only finish verification: other
pages and the API answer mfa_required.
Adding or removing a factor, changing your password, linking or unlinking a provider and creating new recovery codes need a recent sign-in. For an enrolled account that means a second-factor check in the last 10 minutes; otherwise a sign-in in the last hour. The dashboard asks you to confirm when it is needed.
Five wrong codes in one session sign that session out. Ten wrong codes across sessions pause verification for 15 minutes and email you.
The dashboard reminds you to add a second factor: a banner on every page, and a prompt on each new sign-in that you can postpone (for a day, or a week after a provider sign-in). Agents, the CLI and MCP never see it.
Lost your factors
- Use a recovery code on the verification page.
- Cloud: contact support. After confirming your identity, support resets your second factor, which signs you out everywhere and emails you.
- On-prem: an organization owner can reset a member's second factor, and the operator can run
bun run src/auth-admin.ts reset-second-factor --email <address>on the server.
Passkeys are bound to the server's hostname. If it changes, use a recovery code or the authenticator app, or ask for a reset.
Sign-in alerts
TheSpider remembers your browsers (a thespider_device cookie, stored on the server only as a hash)
and the networks you sign in from (a /24 or /56 network prefix, stored only as a keyed hash). When a
sign-in comes from a browser and a network it has not seen before, you get an email, "New sign-in
to TheSpider", with the time, method, browser and network. On a server without email, the next page
you open shows the same notice instead.
If it was not you, choose Secure my account (the email link opens a confirmation page; nothing happens until you confirm). That:
- signs out every browser session and forgets every remembered browser,
- revokes CLI tokens and MCP authorizations created since that sign-in (older ones are listed on Account → Security for review),
- removes the password if the intruder used one (sign in with a reset link or a provider), and
- emails you a confirmation.
Other protections
- Password reset signs out every session.
- Breached passwords are refused on sign-up, password change and reset (
PASSWORD_COMPROMISED). The check sends only the first five characters of the password's SHA-1 hash to Have I Been Pwned. It is on in Cloud and off on-prem by default. - Repeated wrong passwords lock that email's password sign-in for a minute, doubling up to 15
minutes (
TOO_MANY_ATTEMPTS); ten from one network lock that network for 15 minutes. Each attempt is reserved before the password is checked: a successful sign-in clears the count, a wrong password keeps it, and anything else gives it back, so many attempts sent at once are limited the same way as attempts sent one by one. A browser that signed in to the account before, a provider sign-in and a password reset all still work, and a completed password reset lifts the lock. - The sign-in, password-reset and verification-email endpoints accept only
application/jsonbodies (415 UNSUPPORTED_MEDIA_TYPEotherwise).
Sessions, agents and integrations
Account → Security lists:
- Signed-in sessions, with browser, IP, sign-in method and whether two-factor was verified. Sign out one, or every other session.
- Agents and integrations: your CLI logins, CLI tokens and MCP authorizations, with how the approving session signed in. Revoke any of them.
- Security activity: the last 30 security events (factors, linked sign-ins, password changes, new sign-ins).
See also Org sign-in policy and Troubleshooting.