Concept
Workspaces and permissions
How MCP connections reach workspaces, the per-call workspace argument, roles and Admin-only tools, sending and full scopes, tokens and revoking access.
An AI assistant connected to Emailit can never do more than you can. What it can do depends on three things: which workspaces you allowed, your role in each one, and the scope you approved.
Workspace access
When you connect, the consent page asks which workspaces the app can use:
| Choice | What the app can reach |
|---|---|
| All my workspaces | Every workspace you belong to, including ones you create or join later |
| Only these workspaces | The workspaces you tick |
If you allow more than one, you also choose where the app starts: its default workspace for requests that don’t name one.
You can change both later under AccountConnected apps with Edit access. Changes apply on the app’s next request, without reconnecting. If you leave a workspace, or someone removes you, the app loses access to it as well.
Choosing the workspace for a request
| Tool | What it does |
|---|---|
get-current-workspace |
Returns the default workspace, your role in it and the granted scope |
list-workspaces |
Lists the workspaces this connection may use, with your role in each |
switch-workspace |
Changes the default workspace for later calls on this connection |
create-workspace |
Creates a workspace, adds it to the connection and switches to it (needs full) |
With OAuth, every tool outside the Workspace toolset also takes an optional workspace argument: a workspace ID or the exact workspace name. It runs that one call in that workspace without changing the default, so two chats working in different workspaces don’t interfere. Assistants pass it when you name a workspace (“In Acme Client, list the domains”).
The default workspace sticks across token refreshes, so a long session keeps working where you left it.
Roles
Tools run with your role in the target workspace, exactly like the dashboard. Owners and Admins can do everything the scope allows. Members can’t:
- create, rename, delete or regenerate API keys (
create-api-key,update-api-key,delete-api-key,regenerate-api-key), - delete sending domains (
delete-domain).
When a Member asks for one of these, the tool returns an admin_role_required error that names the workspace and your role, and nothing changes. Ask a workspace Admin to do it, or to change your role. The same role checks apply to OAuth calls to the REST API.
Scopes
| Scope | Tools |
|---|---|
sending |
send-email, update-email, cancel-email, retry-email, forward-email, get-current-workspace, list-workspaces, switch-workspace |
full |
Every tool, including all of the above |
Most AI tools request both scopes. When a connection without full calls a tool that needs it, the tool returns a missing-scope error. Clients that support step-up authorization, such as ChatGPT, show the Emailit approval screen again so you can grant full; with other clients, revoke the connection and reconnect with full access.
API key connections are different: the server hides tools the key can’t call, so a Sending Only key only ever sees the sending tools.
Tokens and sessions
| Lifetime | |
|---|---|
| Access token | 15 minutes |
| Refresh token | Up to 60 days of inactivity, rotated on every use |
Reusing an old refresh token revokes the whole connection, which protects you if a token leaks. The MCP server itself is stateless, so there is no session to expire; clients refresh tokens in the background.
API key connections
An API key acts on the workspace it was created in. It has no workspace argument, no access to the workspace tools that need OAuth (list-workspaces, switch-workspace, create-workspace) and no role limits, because the key itself carries the permission. Create a Sending Only key for agents that only send.
Review and revoke access
AccountConnected apps lists every app you approved, the workspaces it can use, its access level and when it connected. Revoke access stops its tokens immediately; it has to ask for permission again to reconnect. See Connected apps, or manage grants from code with the grants API.