Security & privacy
This page explains what Workstate stores, who can reach it, and how to remove it. It also lists the security features that are not built yet, so you can decide what to connect.
At a glance
- Signing in with GitHub gives Workstate no access to your repositories.
- Workstate only reads from the sources you connect, and only the parts you choose.
- Each person has their own API keys. Workstate stores only a one-way fingerprint of each key.
- Namespaces keep indexes apart. A request can't reach a namespace that its person has no access to.
- Everyone with access to a namespace can see everything indexed in it.
- Deleting a source removes what Workstate indexed from it.
What Workstate stores
| What | Why | How |
|---|---|---|
| Your GitHub user id, username and verified email addresses | To sign you in and to match invitations | Only verified addresses are used |
| Console sessions | To keep you signed in, for up to 7 days | Stored as SHA-256 digests (one-way fingerprints) |
| API keys | To let your agents connect | Stored as SHA-256 digests. Each key is shown once, when it is created |
| Source settings | To sync each source | For Confluence and Jira, this includes the site, the account email and the API token. The token is encrypted |
| A working copy of each source's content | To index it, and to see what changed at the next sync | Repository files from the default branch, Confluence pages and Jira issues saved as text, and the files you upload |
| The search index | To answer searches | Passages of text with where each came from (repository, path and lines), and a vector for each: a list of numbers used to match by meaning |
| The ledger | It is your decision record | Every topic and entry, with the author's email address and the agent label |
| Sync history, and when each key was last used | To show status in the console | Kept with the source or the key |
When you sign in, and when you connect the GitHub App, GitHub gives Workstate a token for your GitHub account. Workstate uses it only to check who you are and what you may connect, and does not store it.
How access works
Signing in
- Sign-in uses GitHub and asks only for
read:useranduser:email: your profile and your email addresses. It grants no access to repositories. - Workstate is invite-only. Someone nobody invited can't create an account by signing in.
- Only email addresses that GitHub has verified can accept an invitation.
- Console sessions last 7 days. Signing out ends the session.
Reading your sources
- GitHub: through the Workstate GitHub App, which is read-only. You choose its repositories on GitHub's own install page. Only an admin of the GitHub organisation, or the owner of the personal account, can connect it. Each installation belongs to one Workstate account at a time.
- Confluence and Jira: through an account email and an Atlassian API token. Workstate checks them against your site before saving them. Use an account that can see only what you want indexed.
- Uploads: only the files that an Owner or Admin uploads.
API keys
- Each key belongs to one person, and everything done with it is recorded as theirs. An agent can't write to the ledger under someone else's name.
- Keys are shown once and stored only as digests.
- Keys don't expire and have no scopes: a key reaches every namespace its person can reach. Revoke keys you no longer use. See API keys.
Namespaces and roles
- Nobody reaches a namespace unless they are given it. Owners and Admins choose which namespaces each person reaches, and can take access away. A change applies to the person's next request.
- Every request is checked against the namespaces that its key or session has access to. A request that names any other namespace is refused.
- A topic or source in another namespace answers "not found", so a request can't even confirm that it exists.
- Inside a namespace, there are no per-document permissions: everyone with access sees everything. Put sensitive material, such as HR or legal documents, in its own namespace. See Managing namespaces.
- Roles decide who can change sources, namespaces and seats. See Roles.
Encryption
- The console and the MCP servers are served over HTTPS.
- Atlassian API tokens are encrypted at rest with AES-256-GCM. Each account has its own data key, and that key is itself encrypted with a key-encryption key that is kept outside the database. Each encrypted token is bound to its record, so it can't be copied onto another account's source and used there.
What Workstate indexes, and what it skips
| Source | Indexed | Skipped or refused |
|---|---|---|
| GitHub | The latest files on the default branch of the repositories you choose: text files up to 1 MB each. No history, pull requests or issues | Hidden files and folders (names starting with a dot, including .env files); dependency and build folders such as node_modules, vendor, target, dist and build; lockfiles; minified files; binary files; empty files; files with very long lines, which are usually generated |
| Confluence | The current version of the pages in the spaces you choose, up to 50 spaces per source | Everything outside those spaces |
| Jira | The issues in the projects you choose, up to 50 projects per source, with up to 500 comments each | Everything outside those projects |
| Upload files | Text and code up to 1 MB each; PDF, Word, Excel and PowerPoint files (.pdf, .docx, .xlsx, .pptx) up to 50 MiB each; up to 2 GiB and 20,000 files per source | Private keys, .env files, and file types Workstate can't read, such as images and archives, are refused |
Remove secrets before you connect a repository
A GitHub source indexes what its repositories hold, apart from the files skipped above. It does not look inside files for passwords, tokens or keys. If a repository has credentials committed to it, anyone with access to the namespace can find them by searching, and agents can quote them. Remove committed secrets, and change them, before you connect a repository. Otherwise, don't connect it. Filtering secrets out of GitHub sources is not built yet Coming soon.
For each source's details, see Sources.
Models that process your content
Workstate turns your content into vectors, and ranks search results, with models that the Workstate deployment runs itself. No outside model provider receives your content today. If Workstate starts to use one, or any other sub-processor for your content, this page will list it before it is used.
Deleting data
| To remove | Do this | What happens |
|---|---|---|
| A source's content | Delete the source (Owner or Admin) | Its indexed content, its stored files and its sync history are removed |
| One repository's content | Stop sharing the repository with the GitHub App, on GitHub | It is removed from the index at the next sync |
| A namespace and everything in it | Delete the namespace (Owner or Admin) | Its sources, index and ledger topics are removed, and its id is never used again. Some deployments switch this off. See Managing namespaces |
| A ledger topic | Archive it | It is hidden from search but kept. Only deleting its namespace removes a topic for good |
| A person's access | On the Team page, revoke their keys and untick every namespace in their row | Their keys stop working at once. A new key they create reaches none of the namespaces you took away. The seat stays, and they can still sign in. See Team & invites |
| Your account | Not built yet Coming soon | To ask about removing an account, email hello@workstate.io |
Uninstalling the GitHub App stops a GitHub source's syncs, but it doesn't remove what was already indexed. Delete the source to remove that.
Not built yet
These are not available today. Plan around them.
- Single sign-on (SSO) and SAML Coming soon
- Exporting an audit log Coming soon
- Per-document permissions inside a namespace Coming soon
- Removing a seat, and deleting an account Coming soon
- Signing agents in with OAuth instead of API keys Coming soon
- Filtering secrets out of GitHub sources Coming soon
- Usage reporting for each person Coming soon
Report a security issue
Email hello@workstate.io. Describe what you found and how to reproduce it. Don't include real passwords or keys in your email, and don't access data that isn't yours while you investigate.