API keys

An API key connects an agent to Workstate. Each key belongs to one person: every search and every ledger entry an agent makes with it is recorded as that person's. Make one key for each machine or agent, so that you can revoke any one of them on its own.

Key facts

What	Detail
Where you create one	The console's API keys page, while signed in. A key can't create other keys
Who can create one	Anyone with a seat, for themselves
What it looks like	It starts with rgc_live_
When you see it	Once, when you create it. Workstate stores only a SHA-256 digest (a one-way fingerprint) of the key, so it can't show the key again
How many	Up to 25 live keys per person
Expiry	None. A key works until it is revoked
What it reaches	Every namespace its person has access to. Keys have no scopes
Label	Required, up to 64 characters

Create a key

1. Open API keys in the console.
2. In Create a key, describe where you'll use it, for example "claude-code on the laptop", and select Create key.
3. Select Copy key. The box is marked "shown once": after you leave the page, the key can't be shown again.
4. Store the key where your agent can read it. See Store your key safely.

The key now appears under Your keys with the status Live.

Connect your agent

The Connect your agent panel ("Paste into .mcp.json") builds the configuration for the namespace you are working in. Select Copy and paste it into your client's MCP configuration. For your oldest namespace, it looks like this:

{
  "mcpServers": {
    "rag-corpus": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/corpus",
      "headers": {
        "Authorization": "Bearer ${RAG_API_KEY}",
        "X-RAG-Namespace": "ws-…"
      }
    },
    "rag-ledger": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/ledger",
      "headers": {
        "Authorization": "Bearer ${RAG_API_KEY}",
        "X-RAG-Namespace": "ws-…"
      }
    }
  }
}

• The file holds no secret. Your client fills in ${RAG_API_KEY} from its environment, so the file can sit in a repository.
• rag-corpus serves search. rag-ledger serves the ledger tools.
• Match the server names to your agent instructions. The instructions refer to the tools by the server names rag-corpus and rag-ledger, so an agent that uses one namespace needs its servers named that way, whichever namespace it is. See Server names.
• For any other namespace, the servers are named rag-corpus-<namespace id> and rag-ledger-<namespace id>. To connect an agent to several namespaces, switch namespace, copy each configuration, and combine them. See Managing namespaces.

Each client is set up differently. See Agents & clients.

To check that it works, ask your agent to search for something you know is indexed. The key's Last used time updates when the key is used.

Store your key safely

• Never put the key in a file that might be committed. That includes .mcp.json, and your shell profile too if you keep it in Git.
• Use one key per machine or agent, so that revoking one doesn't stop the others.
• Don't share keys. Everything done with a key is recorded as its owner's.

In an environment variable

Set RAG_API_KEY in the environment your agent runs in, for example in your shell profile:

export RAG_API_KEY='rgc_live_…'

Desktop apps may not see it

On macOS, apps opened from the Dock or Finder don't read your shell profile. For them, ${RAG_API_KEY} is empty, and every call fails with 401. Use the Keychain method below instead.

In the macOS Keychain, with Claude Code

Claude Code can run a small script, called a headersHelper, that prints the request headers each time it connects. The key then lives only in your Keychain.

1. Add the key to the Keychain. The command asks for the key, so it stays out of your shell history:

   security add-generic-password -U -a "$USER" -s workstate-api-key -w

2. Save this script, for example as ~/.config/workstate/mcp-headers.sh, and make it executable with chmod +x:

   #!/bin/sh
   key=$(security find-generic-password -a "$USER" -s workstate-api-key -w 2>/dev/null) || {
     echo "No Keychain item named workstate-api-key" >&2
     exit 1
   }
   printf '{"Authorization": "Bearer %s"}\n' "$key"

3. In .mcp.json, remove the Authorization header from each Workstate server and add headersHelper with the script's full path. Keep the X-RAG-Namespace header:

   {
     "mcpServers": {
       "rag-corpus": {
         "type": "http",
         "url": "https://mcp-uat.workstate.io/corpus",
         "headers": { "X-RAG-Namespace": "ws-…" },
         "headersHelper": "/Users/you/.config/workstate/mcp-headers.sh"
       },
       "rag-ledger": {
         "type": "http",
         "url": "https://mcp-uat.workstate.io/ledger",
         "headers": { "X-RAG-Namespace": "ws-…" },
         "headersHelper": "/Users/you/.config/workstate/mcp-headers.sh"
       }
     }
   }

For more on Claude Code, see Claude Code.

Revoke a key

1. Open API keys.
2. Under Your keys, find the key by its start, such as rgc_live_1a2b3c4d••••, or by its label.
3. Select the trash icon, Revoke this key.

The key is revoked at once. There is no confirmation step, and a revoked key can't be restored. Its status changes to Revoked, and agents that use it get 401 on their next request. Revoked keys stay in the list for reference.

An Owner or Admin can revoke all of a teammate's keys at once. See Revoke a person's keys.

Rotate a key

There is no rotate button. To replace a key without a gap:

1. Create a new key.
2. Put the new key where your agent reads it: the environment variable or the Keychain item.
3. Restart the agent and check that it can search. The new key's Last used time updates.
4. Revoke the old key.

Rotate a key when someone else may have seen it, when a machine is lost, or when you stop using a machine.

When a key stops working

A request with a missing or unusable key gets HTTP 401 (Unauthorized). The response is the same whatever the reason:

{"error":"unauthenticated","detail":"invalid or revoked key"}

If no key was sent at all, the detail is "missing bearer token". Your client may show either as a failed connection. Check these causes in order:

1. The key is empty. RAG_API_KEY isn't set where the agent runs. See Store your key safely.
2. The key was revoked, by you or by an admin. Its status under Your keys is Revoked. Create a new key.
3. The key was copied wrongly, with a character missing or added.
4. The key was issued by a different Workstate deployment. A key works only with the deployment that issued it.

Other messages you may see:

Message	What it means
"you already hold 25 live keys; revoke one you no longer use first"	You have reached the limit of 25 live keys
"a key needs a label saying where it is used"	The label was empty
"no grant for namespace …"	The X-RAG-Namespace header names a namespace you don't have access to. See Managing namespaces
"principal has no workspace grants"	You don't have access to any namespace yet. Ask an Owner or Admin to give you one on the Team page

Related

• Keys & attribution
• Team & invites
• Managing namespaces
• Limits & defaults