Concept

Access and keys

See every way into your workspace on one page, understand grants, scopes and presets, limit one, and revoke it.

One page for every way in

Everything that can act on your workspace is a grant, and the Access page in the dashboard lists them all in one place:

GroupWhat it is
Connected appsChatGPT, Claude, Cursor and other apps you allowed with OAuth (connect one)
API keysSecret keys for your servers and the SDK, MCP keys, and the keys of voice agents you host
Connected computersA machine you connected with npx voicelayer connect
PluginsInstalled plugins, each acting with the permissions you approved

Each row shows what the grant may do, who allowed it and when, when it last acted, and anything it was refused this week. A grant that has never been used, or not for 30 days, says so in words. Most "is this key still in use?" questions are answered by looking.

To make one, choose New:

Scopes

A grant can do exactly what its scopes say, and nothing else. A key with only messages:read cannot send. There is no hidden default role: a scope is the whole permission set. This table is the full list a key or an app can hold.

ScopeLets the grant
messages:sendSend messages and replies on any channel, and write, edit, send or throw away drafts
messages:readRead conversations, messages and drafts
conversations:controlDecide who answers a conversation
conversations:manageArchive, label and mark conversations as handled or read
conversations:deleteMove conversations to the trash and bring them back
conversations:purgePermanently delete conversations and everything in them
retention:manageSee and change how long conversations are kept and how the trash works
events:readWatch what happens in your workspace as it happens (webhook, stream, pull)
channels:readSee which channels your workspace can use
webhooks:manageCreate and change webhook subscriptions
logs:readRead your API request logs
mcp:call.startPlace calls and plan them
mcp:call.tailSee your numbers and follow calls
mcp:call.controlSpeak on, steer, send keypad tones to and hang up calls in progress
mailbox:useRead and send email from mailboxes that already exist
mailbox:manageCreate, pause and release mailboxes, and use them
email_domain:readSee the domains your agents send and receive email on
email_domain:manageAdd, check and remove those domains
memory:readRead what your agents remember about people
memory:writeAdd to what your agents remember
memory:eraseErase a person's memory
memory:adminManage memory spaces and merge people
calendar:useConnect a calendar, make one for an agent, see and move meetings, and book people into free times
public_access:readSee how open your website sessions are
public_access:writeChange how open your website sessions are (opening them up also needs workspace:admin)
workspace:readSee your agents, flows, settings and reports
workspace:writeBuild and change agents, playbooks, flows, tools, numbers you own, channels and settings
workspace:adminLoosen your own limits: who can reach your agents, which countries they call, what they may do on their own
room_logs:readRead what your hosted agents print in their rooms, which can include what was said on calls
people:manageChange people's roles, answer access requests, and cut off or limit keys, apps and computers
keys:manageMake and delete API keys (a key it makes can do no more than it can)
billing:readSee the balance, prices, charges, invoices and spending limits
billing:manageSet spending limits and auto top-up, and approve provider fees. It cannot add or change a card
sdk:read, sdk:writeRead and register agents and call results through the SDK. Together they are full access for a key made for "Your servers or the SDK": it passes every scope check except people, keys, billing and loosening limits
telemetry:writeSend your own traces, metrics and logs to VoiceLayer

A few more scopes exist, but VoiceLayer sets them itself on keys it makes for you (the website chat widget, hosted agent workers, image pushes, connected computers). You never choose them.

An MCP host sees only the tools its scopes allow. A call outside them is refused with 403 insufficient_scope, and details.required names the scope.

API key kinds

Access → New → Create API key asks what the key is for, and that choice sets its scopes. You do not pick scopes one by one.

  • Your servers or the SDK: a secret key with full access for the API: sdk:read and sdk:write, which pass every scope check except people, keys, billing and loosening limits.
  • Cursor, Claude Code, or another MCP client: mcp:call.start, mcp:call.tail, mcp:call.control, messages:send, messages:read, events:read, channels:read, conversations:control and conversations:manage, tagged mcp:client. It places and follows calls and uses the messaging tools, including message_send, which can send email from a mailbox that already exists. It has a $20 monthly spend cap and two concurrent calls by default. Of the manage_<area> tools it sees only manage_agents and manage_calls. It sees no memory, mailbox, calendar or hosting tools, and cannot create or manage mailboxes. Which tools each connection sees is on Connect an AI agent.
  • The chat widget on your website: a publishable key. VoiceLayer sets its scopes: it only starts and sends chat messages from the sites you list.
  • The workers that run your agent code: a worker key for one environment. VoiceLayer sets its one scope: it connects your workers and cannot call the API.

Presets

When you connect an app, you choose a preset instead of a list of scopes:

  • Messages and inbox: read and send messages on every channel, decide who answers, archive, label and trash conversations, set up and use mailboxes and email domains, and use the calendar. (messages:send, messages:read, conversations:control, conversations:manage, conversations:delete, events:read, channels:read, mailbox:manage, email_domain:manage, calendar:use.) Permanent delete and retention are not in it.
  • Calls: place calls, follow them and steer them, and see your numbers. (mcp:call.start, mcp:call.tail, mcp:call.control.)
  • Build and run agents: build and change agents, flows, tools and channels, run campaigns (which place calls), use memory, send messages, and read what hosted agents print. Not people, keys or billing. (workspace:write, room_logs:read, mcp:call.tail, memory:read, memory:write, channels:read, messages:send, messages:read, conversations:control, events:read, calendar:use.)
  • Look, don't touch: see your agents, conversations, calls, memory, spending and logs. Nothing it holds changes anything. (mcp:call.tail, memory:read, messages:read, events:read, channels:read, logs:read, room_logs:read, public_access:read, workspace:read, billing:read.)
  • Everything: everything you can do in the dashboard: every scope in the table above except sdk:read, sdk:write and telemetry:write. Two things stay in the dashboard for every app: entering or changing a payment card, and buying a phone number. For spending actions (auto top-up, a provider fee, starting a campaign) and giving a number back, VoiceLayer asks the assistant to confirm the details with you first. Only an admin can connect an app with Everything.
  • Choose…: switches by area, each one or more of the scopes above. people:manage, keys:manage, billing:manage, memory:admin and workspace:admin need an admin; anything outside the list is refused with scope_not_consentable.

Limit one

Limit to… on an app, a computer or a plugin narrows it to one Line or one mailbox. It only ever narrows: the grant keeps working inside the limit and is refused outside it, with a reason you can read on the row. To widen, connect again.

Revoke

Revoke ends a grant and tells you the consequence first. After you confirm:

  • A connected app's next call is refused with token_revoked, and its refresh token stops working. Nothing waits for the token's ten-minute expiry.
  • An API key stops working at once.
  • Calls already in progress finish; it is the next call, message or token refresh that fails.
  • The change is one entry in the access log: who revoked it, and when.

Every grant on the workspace stops within a minute of a revoke, everywhere (every API server and the edge), because they all follow the same version feed.

Who may change what

A signed-in person with the right role makes and revokes grants. A key or an app never makes another key. An app may narrow a mailbox it has been given (turn review before send on) but a person decides when to loosen one; see Give an outside agent an inbox.

A person at VoiceLayer acting for you under support access leaves their own entry in the access log and cannot create a key or an app that would outlive the visit.

Next steps

On this page