Keys and scopes

Make a Space API key, choose what it may read, write and run, and understand the limits that sit on top of scopes for agent keys.

Everything you build against Wakato starts with a key. A key decides which Space you act in and what you may do there. The same key works for the REST API, the MCP server and the AI Gateway.

Two kinds of key

Prefix	What it is	Where you make it
`wks_live_…`	A Space API key. Locked to one Space. Powers `space-api`, `space-mcp` and `gateway-endpoint`.	Space → Settings → API Keys
`wka_live_…`	An Account API key. Acts on your account: creates Spaces, funds them, mints Space keys.	Backstage → API Keys

This page is about Space keys. Account keys have their own scopes, spend limits and space containment; see Account MCP.

Send a key as Authorization: Bearer wks_live_…. The x-api-key: wks_live_… header is accepted too, which is what the Anthropic SDK sends.

Make a Space key

Open the panel

In Wakato: Space → Settings → API Keys → New API key. Only the Space's owner and admins can make or change keys.

Name it and pick an expiry

Name it after what will use it ("Cursor, marketing site"). Expiry is one of no expiry, 7 days, 30 days, 90 days or 1 year.

Choose scopes

The dialog starts on Full access. Switch to Read only or Custom to narrow it. If you grant the Space Gateway, you can also limit the key to selected models.

Copy the token

The wks_live_… token is shown once, beside the MCP server URL and the AI Gateway base URL. Wakato stores only a hash of it.

Scopes

A scope is a category plus an action:

read: list and inspect.
write: create and edit. For most categories this means drafts.
run: the live action. Publish a page, send an email, post to social, run an automation.

The full catalog below is what Full access grants. Each MCP tool and REST route declares the one pair it needs.

Category	Actions	Covers
`ai`	run	The Space Gateway: models enabled in the Space, billed to its wallet
`services`	read, run	Gateway services: search, scraping, transcription and more
`contacts`	read, write	People in the Space
`tables`	read, write	Tables and their rows
`pages`	read, write, run	Pages, sites, booking pages; run publishes
`forms`	read, write	Forms and submissions
`assets`	read, write, delete	The asset library
`documents`	read, write	Collaborative documents
`whiteboards`	read, write	Whiteboards
`automations`	read, write, run	Automations and their runs; also events and webhooks
`apps`	read, write, run	Space Apps; run publishes
`reach`	read, write	An agent's External Reach
`social`	read, write, run	Social accounts, drafts; run publishes
`messaging`	read, run	The DM and comments inbox; run replies
`ads`	read, write	Ads Manager
`agent_mail`	read, write, run	Mailboxes, campaigns; run sends
`calendar`	read, write	Calendar events
`tasks`	read, write	Tasks and projects
`meet`	read, write	Meetings and rooms
`phone`	read, write, run	Numbers, calls, SMS; run sends
`finance`	read, write	The books. Write keeps them; it never moves money
`integrations`	read, write	Connected services; write only asks a person to connect one
`secrets`	read, write, run	Secret names. Values are never returned
`wallet`	read	Balance and usage
`space_settings`	read, write	Space settings
`pass`	read, write	Wakato Pass cards
`commerce`	read, write	The shop run from this Space
`communities`	read, write	The Space's community
`profiles`	read, write	The business behind the shop
`self`	read, write	An agent's own name, picture and setup list
`agents`	write	Making agents

Two actions are opt-in only. Full access never includes them, so you tick them by hand:

apps:delete: permanently delete a Space App and all its data.
self:instructions: let an agent rewrite its own instructions. Every change is kept and shown in its chat.

An under-scoped key hides tools

tools/list on the MCP server is filtered by scope. A tool the key cannot call is not listed, and there is no error. When an agent says it "can't" do something, check the key's scopes first.

What no scope allows

Whatever you tick, a Space key cannot reach another Space, read your login, manage members, move money out of the Space or read a secret's value.

Keys are edited in place: Space → Settings → API Keys → Edit. You can change the name, scopes (add or remove), the model list, the expiry and the tool catalog (Everyday tools or Every tool, see Cursor and Claude Desktop). The token does not change, so whatever uses the key keeps working under the new scopes. A revoked key can't be edited.

Agent keys: ask first, Can use and levels

When a key belongs to one of the Space's own agents, two more layers sit on top of its scopes. A key you made for your own tools has neither.

Ask first. The owner can mark any scope pair as "asks first". A call that needs it does not run: it becomes an approval card in the agent's chat, and runs once a person allows it. Some tools always ask, whatever the policy.

Can use. Per Space, the owner can name exactly which tables, documents, apps, pages, forms, folders, automations and secrets the agent may touch. A call naming anything else is refused by name, never queued. Lists come back filtered. Nothing named means everything.

Levels. A thing on that list can carry a level on its kind's ladder. For a table: read, edit (change what rows say), fill (add and remove rows), change (columns, views, settings, delete). Apps go read, use, build; pages go read, content, edit, change. A refusal says how far the agent may go.

An agent asks for a missing permission with the request_permission tool, which posts a card in its chat. See the agent tools.

Rotating and revoking

There is no "rotate" button, by design. Rotation is three steps:

Make a new key with the same scopes.
Update the environment variable or secret that holds it.
Revoke the old one in Space → Settings → API Keys.

Revocation is immediate. The next request with that key gets 401 with "This Space API key has been revoked". An expired key answers 401 too. For habits that keep keys out of files and logs, see Safe agent setup.

Keys and scopesone key, exactly the doors you open.