Docs / Teams and workspaces
Team and account security
A workspace can have several people, each with a role. One person can belong to several workspaces and switch between them. This page covers roles, invitations, password reset, two-factor authentication, sessions and the audit log.
Roles
| Area | Viewer | Member | Admin | Owner |
|---|---|---|---|---|
| Read emails, logs, statistics, templates, campaigns, contacts, inbox and settings | Yes | Yes | Yes | Yes |
| Send email; manage templates, campaigns, automations, contacts, lists, segments, imports and suppressions; track events | Yes | Yes | Yes | |
| Inbox: reply, compose, drafts, notes, labels and rules; AI assistant | Yes | Yes | Yes | |
| Sending providers, routing, domains, DNS hosts, mailboxes and webhooks | Yes | Yes | ||
| API keys, workspace settings, AI provider connections | Yes | Yes | ||
| Team: invite, change roles, remove members; audit log | Yes | Yes | ||
| Transfer ownership | Yes | |||
| Download a data export of the workspace | Yes | Yes | ||
| Delete the workspace (7-day grace period) or cancel the deletion | Yes |
- Each workspace has one owner. The owner's role cannot be changed and the owner cannot be removed or leave; the owner can transfer ownership to another member (with their password, and a two-factor code if it is on). The previous owner becomes an admin.
- Nobody changes their own role. Anyone except the owner can leave a workspace, unless it is their only one.
- Viewers are read-only everywhere, including SMTP and the compatibility endpoints when they use a session token.
- Every person can manage their own account (profile, password, two-factor, sessions) whatever their role, and delete it when they own no workspace. See Privacy for data export and deletion.
The server checks roles in one place for every endpoint (requiredRole in apps/server/src/services/team/permissions.ts): reads are open to viewers, except API keys, the audit log and pending invitations; changes to the admin areas above need admin; other changes need member. A role that is too low gets 403 insufficient_role.
API keys are not people. A key belongs to one workspace and is limited by its own permission (Full access, Sending only, Read only, Admin), not by a role. Full access is the data plane: sending, reading and managing content (templates, contacts, lists, campaigns, automations, forms). Configuration, the areas only admins may change above (sending providers, routing, domains, DNS hosts, webhooks, workspace settings, AI connections, mailboxes, inbound endpoints, the license, API keys and the team), needs a live Admin key; other keys get 403 insufficient_scope (enforcePlane in apps/server/src/lib/auth.ts). Owner-only actions need the owner, signed in. Test keys never change configuration. New keys are Sending only unless another permission is picked, and a key can only create keys no wider than itself, and at most 100 that are not revoked, expired ones included (ONESEND_MAX_KEYS_PER_KEY; over it: 400 too_many_keys; keys created in the dashboard are not limited). A key can rotate only itself and the keys in its own creator chain (403 not_in_key_chain otherwise).
An Admin key is a root credential for the workspace. It can change the workspace's configuration, invite people and change members' roles, and manage API keys. Revoking it (or a leak report about it) revokes the keys it created or rotated, cancels its invitations and removes the people who joined through them, and turns off the inbox rules, mailbox forwarding and automation webhook steps it set up (see Revoking a key). Some of what it did stays after it is revoked, by design, because it is ordinary workspace configuration that the workspace may depend on:
- webhook endpoints, sending connections (providers) and domains it added;
- campaigns it scheduled;
- role changes it made to existing members (an existing member it made an admin stays an admin);
- other configuration it changed (routing, workspace settings, DNS hosts, inbound endpoints).
Use Sending only or Full access keys for applications. Create an Admin key only when an application really needs to change configuration, give it an expiry (expiresAt) and the addresses it may be used from (allowedIps), and after revoking one, review the audit log (filter by the key) for the changes above.
Removing a member (or their leaving the workspace, or deleting their account) turns off what they set up that sends mail out of it, nothing is deleted:
- the API keys they created are revoked, including keys created through a key they created; revoking or a leak report of any key also revokes the keys it created, recursively (see Revoking a key);
- their inbox rules that forward outside the workspace, call a webhook or deliver into a mailbox that does are turned off (
disabledReason: member_removed), and so are the rules and mailbox settings their revoked keys made (key_revoked); - the outside forwarding (
forwardTo) and webhooks they set on mailboxes are turned off (forwardingDisabledReason), and the mailboxes they connected are paused.
The owners get one security alert listing what was turned off. Setting a mailbox's outside forwardTo or webhookUrl needs an admin (signed in, or a live Admin key), and each outside address receives mail only after its owner confirms a link emailed to it (valid 14 days). What OneSend turned off stays off until an admin turns it back on (Turn back on on the rule or mailbox): saving it again does not, and the owners are alerted again.
Limitation: keys and mailbox or rule setups created before migration 0034 by an API key whose creator is not recorded are not tied to any member, so they survive that member's removal. Review admin keys created before 0034 (in GET /v1/api-keys, createdByUserId and createdByKeyId are both null) and rotate or revoke the ones nobody can account for; revoking such a key still revokes the keys it created since migration 0035 and turns off the rules and forwarding it set up.
Revoking a key
Revoking an API key, or a leak report about it, also undoes what it left behind:
- The keys it created, and the keys it rotated, and the keys those created or rotated, until none is left. A key may rotate only itself and the keys of its own creator chain, and the key that made a rotation is recorded (
secret_issued_by_key_id, migration 0037; a rotation in the dashboard clears it), so a secret a key obtained by rotating stops when that key is revoked. Each level of the chain is revoked in one database statement (per chunk of a few dozen to a few hundred keys), and a final sweep catches a key created while the revocation ran; a key created or rotated by a key that is being revoked is revoked too (401key_revoked). Each key gets anapi_key.revokedaudit entry (reasoncreator_key_revokedorcreator_key_leaked;secret_issuer_key_revokedfor a key reached only because the revoked key rotated it) and what it set up stops, as for the key itself. - The invitations it sent. Pending ones are canceled at once. A person who joined the workspace through one is removed, as if an admin removed them (see Removing a member above): their sessions, API keys, rules, forwarding and connected mailboxes stop. The same goes, recursively, for the invitations that person sent: their pending invitations are canceled, and the people who joined through them are removed, and so on. Prior members are kept: someone who was already a member when they accepted such an invitation (accepting did not add them) is never removed, and neither is the owner. Up to 10 people are removed in the request; more continue in a background job. An invitation an admin sends again from the dashboard is no longer tied to the key. An invitation can also no longer be accepted once the person who sent it is not a member, or the key it was sent with is revoked (400
invitation_revoked). - What the keys set up that sends data out: inbox rules that forward outside the workspace or call a webhook, mailbox forwarding and webhooks, and automation webhook steps (
webhookDisabledReason: the steps are skipped, the rest of the automation runs; an admin saving the steps turns them back on). About two minutes after the chain is done, a final sweep turns these off again for every key revoked with it, for something a request that was already running set up meanwhile. What an Admin key changed in the workspace's configuration stays (see the note on Admin keys above).
The owners get one alert with the number of keys revoked (and another listing the canceled invitations and naming every member removed). A very large chain does not have to finish in the request: the keys are revoked first (on Cloudflare Workers, as many levels as fit in the request's statement budget), and the audit entries, the turning off of what the keys set up and the rest of a very deep chain continue in background jobs. The alert then says that the rest continues in the background, and a second alert gives the total when it is done, the invitations canceled in the background included.
What the limit bounds: a key may have at most 100 keys it created that are not revoked, expired ones included (ONESEND_MAX_KEYS_PER_KEY), and a key making an expired key live again (PATCH with a later or no expiresAt) is held to the same limit. This bounds the keys each key creates directly. Keys a key creates are never Admin keys (those are created only in the dashboard), so they cannot create keys themselves: one leaked Admin key can hold at most 100 keys it made at a time, plus its own secret. The limit is per creating key, not per workspace: each Admin key made in the dashboard has its own 100.
Invitations
Admins invite people under Settings → Team → Invite, by email and role (admin, member or viewer).
- The invitation email is a system email sent through the workspace's own sending providers and routing. Its link works for 7 days. The link carries a signed token for invitations only; the token is in the URL fragment (
/invite#token=…), so it does not reach server logs. - Resend sends a new link and restarts the 7 days; the previous link stops working. Revoke makes the link stop working at once. Inviting an address again does the same as Resend and updates the role.
- An invitation sent with an API key (an admin key can invite) is tied to that key (
invited_by_key_id): revoking the key, or a leak report about it, cancels the invitation and removes a person who joined through it (see Revoking a key). An invitation sent or resent by a signed-in admin is not tied to any key. Invitations by API key keep working for every role; only their lifetime is bound to the key. - Someone who already has an account signs in as the invited address and accepts. Accepting with a different signed-in address is refused.
- Someone without an account creates one on the invitation page. This works whatever
ONESEND_SIGNUPis (invite,first-userorclosed): the invitation is the permission. WithONESEND_SIGNUP=invite, invitations are the only way to create accounts after the first one. - If the workspace only has the Sandbox provider, the invitation email is logged but not delivered. The dashboard then shows the invitation link (and the API returns it as
link) so an admin can send it another way.
System emails never keep their one-time links: the stored message (visible under Logs) holds a placeholder, and the real body is kept encrypted in the delivery job only until it is handed to the provider.
Multiple workspaces
The workspace switcher at the top of the sidebar lists every workspace you belong to with your role there. Switching changes the current workspace of your session on the server (POST /v1/auth/workspace); a new sign-in starts in the workspace you used last. Scripts that use a session token can also send X-Workspace-Id on each request. API keys always act in the workspace they were created in.
Passwords
Forgot password. The sign-in page links to Forgot password?. The server answers the same way, in the same time, whether or not an account exists for the address. The reset email goes through the router of a workspace the account belongs to (one with a real sending provider, preferring workspaces the person owns or administers). The link works once, for 30 minutes, and stops working if the password changes in the meantime. Resetting signs the account out everywhere. Accounts with two-factor authentication also enter a code or a recovery code.
When the server cannot send email yet (only the Sandbox provider), create a reset link on the server itself. The command opens the database directly, so it runs on the machine that has the database and ONESEND_SECRET, never over HTTP:
npm run admin -- reset-password person@example.com
# Docker (the Compose service keeps its name from before the rename): docker compose exec openemail node apps/server/bin/onesend-admin.mjs reset-password person@example.com
It prints a one-time link that works for 30 minutes. npm run admin -- disable-2fa <email> turns off two-factor authentication for someone who lost both their authenticator and their recovery codes, and npm run admin -- list-users lists accounts and their workspaces. Each of these is recorded in the audit log.
Change password is under Account and needs the current password. It signs out every other session.
Change email is under Account and needs the current password. A confirmation link (24 hours) goes to the new address; the address changes when it is opened, and the old address gets a notice. If the new address already belongs to an account, the answer is the same and nothing changes.
Rate limits: reset requests per client and per address (extra requests for an address are dropped silently), token pages per client, password confirmations and two-factor codes per account, and invitations per workspace. Over a limit, the API answers 429 with Retry-After.
Two-factor authentication
Turn it on under Account → Two-factor authentication: confirm your password, scan the QR code with an authenticator app (or enter the setup key shown under it; TOTP, RFC 6238: SHA-1, 6 digits, 30 seconds; the otpauth:// link works on phones with an authenticator app), and enter a code. The QR code is drawn in the browser from the otpauthUrl; the setup key never leaves the page. You get 10 recovery codes, shown once; each works one time instead of a code. The secret is stored encrypted with ONESEND_SECRET, recovery codes as hashes, and a code cannot be used twice.
Signing in then takes two steps. Over the API, POST /v1/auth/login answers 401 mfa_required with error.details.mfaToken (valid 5 minutes); send it with code or recoveryCode to POST /v1/auth/login/2fa to get the session.
Require it for a workspace under Settings → Team → Security (admins; turn it on for your own account first). Members whose session did not sign in with two-factor can then only use their own account pages (403 two_factor_required elsewhere) until they turn it on and sign in again.
Sessions
Account → Signed-in devices lists your sessions with the device (from the browser's user agent), a keyed hash of the IP address (the address itself is not stored), when it signed in and when it was last active. Sign out one device, or every device except this one. Sessions last 30 days.
Audit log
Audit log (admins and the owner) records, per workspace: members joining, leaving and being removed; role changes and ownership transfers; invitations created, resent and revoked; the two-factor requirement; account security events of members (password reset or change, email change, two-factor on or off, recovery code used); and changes to API keys, sending providers, routing, domains, DNS hosts, mailboxes, webhooks, workspace settings and AI provider connections. Entries name who made the change (a person or an API key) and keep only field names and non-secret values, never request bodies or credentials. Filter by area and date, page through older entries, or export CSV (GET /v1/audit-log/export).