Get Your API Keys

You need one key per server, and they come from different places. This is not an oversight — the two credentials answer to different authorities.

Hub gives you both a UI and a CLI because its key is an operator credential — useful to mint from a script on a headless box. Memory’s key is a per-user credential tied to your signed-in session, so the UI is the only route; there is deliberately no memory-side CLI.

The Companion Hub key

From the web UI

Open the Hub dashboard and go to Settings → Security. The API keys card sits below two-factor authentication; Create key mints one, and its raw value is shown only at creation.

Each row shows the key’s prefix and carries its scopes and capability as chips. Change access adjusts the capability — scopes are fixed at creation and render as read-only badges. Revoke deletes the key.

From the CLI

Run this on the appliance host, not on the machine running your agent:

cihub api-key create --name "my-laptop-openclaw"

The full form, if you want to be explicit:

cihub api-key create \
  --name "my-laptop-openclaw" \
  --scopes mcp \
  --capability read

List what exists — this prints IDs, names, scopes, capability and a key prefix, but never the key itself:

cihub api-key list

The Companion Memory key

Open Settings

Sign in to Companion Memory and go to Settings → API Keys. The create control is the + button in the top right of the panel, not a labelled button in the empty state.

Name, expiration, access and capability are all fields of the same dialog — you fill them in before the key exists, not after.

Name it

Give it a name that identifies the client you are connecting, so you can revoke precisely later.

Tick the areas it may reach

The scope checkboxes are grouped under Access. For MCP you must select both MCP and Intents. See the scope trap below — this is the single most common setup mistake.

The dialog warns about both traps itself: the MCP checkbox reads “pair with Intents to see any tools”, and the note under the group confirms the key “is limited to the selected areas and is refused everywhere else, including bulk ingest and GraphQL.”

Add Memory if the key will be used for anything beyond MCP — including first-class memory: the passive-capture provider talks REST, so a key without Memory is refused on every call it makes, silently. Ticking all three (Memory, Intents, MCP) yields one key that covers both the MCP setup and the provider.

Get this right the first time. Scopes cannot be changed after creation — the edit dialog offers only the name and the capability. A key with the wrong access has to be replaced.

Choose a capability

Under What this key can do, the dialog labels these Read-only, Read & write, and Read, write & delete — the same three levels this page calls read, write, and full. See Choosing a capability.

The dialog starts on Read & write, as in the screenshot above. For a client whose job is recall, change it to Read-only — that is a deliberate step, not the default. The exception is a key for first-class memory: passive capture writes, so that key must stay on Read & write — on a Read-only key, recall works and every capture is silently refused, which looks exactly like a healthy setup that never remembers.

Create it, and copy the key

The key is shown once, on submit, under “Your new API key has been created” — and the panel tells you plainly that “the key value won’t be shown again.” Store it in your password manager or export it as an environment variable now.

Once you dismiss that banner the key row keeps only a short prefix — redacted in the screenshots above — alongside its scope chips and its capability. Enough to identify the key, never enough to use it.

Scopes: which surface the key opens

Scopes say where a key may go. They are not the same thing as capability, which says what it may do once it gets there.

Different jobs need different scopes. If you are wiring MCP and want your agent to reach the memory REST API, you need MCP + Intents + Memory. A key minted for MCP alone will connect over MCP and return 403 on every /api/memory/* request.

Choosing a capability

Capability says what a key may do on the surfaces its scopes opened. It is a separate axis, and every key has one.

Prefer read unless you want the agent changing things. A key that only needs to recall memories does not need permission to uninstall your apps, and a key pasted into a third-party client is a key you no longer fully control.

Capability also filters what your agent sees. A read key’s tools/list returns only the tools it could actually call, so the agent never wastes a turn on a tool that was always going to be refused.

The two app-proxy tools are gated differently

hub_call_app_api proxies an HTTP call to an app, so what it does depends on the arguments. It appears in every capability’s tool list and the decision is made per call from the method.

The dividing line is narrower than it looks: only GET, HEAD and OPTIONS count as reading. Everything else — POST, PUT, PATCH, DELETE — is treated as destructive and needs full. So a write key can see this tool and use it to read, but is refused for every mutating method, the same as a read key. An unrecognised or missing method counts as mutating.

If your agent needs to drive an app’s HTTP API beyond reads, full is the only capability that works.

hub_call_app_tool is gated the other way. A bridged tool’s effect is opaque to the Hub, so it is flagged destructive outright rather than judged per call — only a full key sees it. If your agent needs to call tools on an app’s bridged MCP server, read and write will not do.

Changing a key later

You do not need to replace a key to change what it can do — but where you do it differs by server.

Revoking

Revoke a memory key from Settings → API Keys with the delete icon on its row, and a Hub key from Settings → Security with Revoke. Because keys are per-client if you minted them that way, revoking one leaves your other clients working.