Security & Access Control

Last Updated: September 2026

How Scrapalot authenticates you, controls who can see what, and protects your data.

Authentication

Sign-in options

• Email/username and password — passwords are hashed with bcrypt and never stored in plain text
• Sign in with Google — Google OAuth; see what Google access is requested
• Desktop app — signs in through your browser and hands the session back to the app, or starts in guest mode (below)
• API keys — scp-… keys for scripts, integrations and MCP clients

Tokens and sessions

Scrapalot uses signed JSON Web Tokens (JWT).

Token	Default lifetime	Notes
Access token	4 hours	Sent as Authorization: Bearer … on every request
Refresh token	90 days	Rotating: every refresh issues a new refresh token, so an active session slides forward; an unused one expires

• Browser clients receive the refresh token in an HTTP-only cookie, out of reach of page scripts.
• The app refreshes the access token automatically before it expires.
• Log out revokes the current session; log out everywhere revokes all of your sessions on all devices.

Self-hosted operators can change both lifetimes (JWT_EXPIRATION_MS, JWT_REFRESH_EXPIRATION_MS).

Guest mode (desktop)

A guest account is not a separate role. The desktop app can create one automatically, tied to the machine, so you can start without signing up. It is a normal user account on the free Researcher plan, with full read and write access to its own content. The one restriction is that it cannot use the bundled Scrapalot AI models, so a guest brings their own provider key until they sign in to a real account.

Authorization

Account roles

• User — standard access to your own content and to anything shared with you
• Admin — platform administration (user management, system settings) on top of normal user access

Workspace permissions

Every workspace has an owner and can be shared with other users. Sharing is available on plans that include shared workspaces.

Role	Can do
Owner	Everything: edit content, share the workspace, change members' roles, remove members, delete the workspace
Editor	Upload and organise documents, create and manage collections, chat with the content. Cannot share, manage members or delete the workspace
Viewer	Browse documents and collections and ask questions. Cannot change anything

Only the owner can share a workspace or change who has access. The person you share with gets an email notification, and access can be revoked at any time.

Note sharing

Notes can be shared individually with read, write or owner permission, independent of workspace sharing.

Data isolation

Every request is checked against your workspace memberships before any data is read or changed:

• You only see workspaces you own or that were shared with you, and the collections, documents, notes and chats inside them
• Writes (uploads, edits, deletes) additionally require edit permission on the workspace
• The AI service only ever receives the workspace, collection and document IDs you are authorised for, so retrieval and chat cannot reach other users' content
• Personal memory ("second brain") is per user; an individual memory is visible to others only if you explicitly share it

API Keys

• Created in Settings → Integrations → Connect your agent or via POST /api/v1/auth/api-keys; requires the Pro plan or higher
• Format scp-xxxxxxxx-xxxxxxxxxxxxxxxx; the full key is shown once at creation — Scrapalot stores only a hash
• Optional expiry date; each key can be disabled or deleted at any time, and shows when it was last used
• A key authenticates as your whole account (same access as you in the web app), so treat it like a password and create one key per client so you can revoke them individually

Data Protection

Encryption

In transit: the hosted service is served over HTTPS/TLS only, including WebSocket connections.

At rest:

• Passwords: bcrypt hashes
• API keys: stored as hashes only
• AI provider API keys you add (OpenAI, Anthropic, OpenRouter, …), connector credentials (Google Drive, Dropbox, …) and MCP integration tokens: encrypted with AES-256-GCM. On self-hosted installs this requires the MCP_ENCRYPTION_KEY setting — see Deployment.

Google sign-in

Signing in with Google requests your email address and basic profile, plus Google Drive's drive.file scope. drive.file only covers files you explicitly pick or create through Scrapalot (for the Google Drive connector) — it does not give Scrapalot access to the rest of your Drive.

Privacy controls

• Incognito chat — a per-conversation mode in which Scrapalot neither uses nor updates your personal memory
• Memory controls — view, export, forget individual memories or purge your personal memory
• Trash — deleted documents can be restored; items in the trash for more than 30 days are purged permanently
• Account deletion — you can delete your own account

Self-hosting for maximum privacy

• Host on your own infrastructure; documents never leave your network
• Use local AI models only (Ollama, LM Studio, vLLM, …) for fully offline operation
• You control backups, retention and access

Rate Limiting

AI requests (chat, deep research, model inference) are rate-limited per user and subscription tier at the gateway. Exceeding the limit returns 429 Too Many Requests with X-RateLimit-Limit / X-RateLimit-Remaining headers. See the API Reference.

Security Best Practices

For users

• Use a long, unique password (a password manager helps) or sign in with Google
• Create one API key per integration, name it after the client, and set an expiry where practical
• Delete keys you no longer use; disable a key immediately if a machine holding it is lost
• Review workspace members and note shares periodically
• Use log out everywhere if you suspect someone else has access to your account

For self-hosted operators

• Serve Scrapalot over HTTPS only, with TLS terminated at your reverse proxy
• Set a strong, random JWT_SECRET (at least 32 characters) — it must be identical for the gateway, backend and AI service
• Set MCP_ENCRYPTION_KEY so provider keys and connector credentials are encrypted at rest
• Change every default database, Redis and Neo4j password before going live
• Expose only the reverse proxy; keep databases and internal service ports on a private network
• Keep images updated and back up regularly

See the Deployment Guide for the full list of settings.

Troubleshooting

Cannot access a workspace

• Make sure the owner shared it with the account you are signed in with
• Ask the owner to check your role (Viewer cannot upload or edit)
• Sign out and back in to refresh your session

API key not working

• Check the key was copied completely (no spaces) and starts with scp-
• Check it is enabled and not expired in Settings → Integrations
• Use the API base URL https://api.scrapalot.app (cloud), not the web app address
• Create a new key if the old one was lost — keys cannot be displayed again

Suspicious activity

1. Change your password
2. Log out everywhere
3. Disable or delete your API keys and create new ones
4. Review workspace members and shares
5. Contact support (or your administrator on a self-hosted install)

Related Documentation

• Database Design - Data storage
• API Reference - Authentication endpoints
• MCP - Using API keys with MCP clients
• Deployment Guide - Production security setup
• User Guide - Using security features