Generate an API key

An API key is one of two ways to authenticate an AI tool — the other is signing in with Orbismo. Keys are the right choice for tools that can’t do a sign-in flow (scripts, bearer-only clients, stdio bridges). They work with a world URL — the per-world endpoint — and each key is scoped to a single world and carries a single permission level.

Create a key

1. Open your world in the portal.
2. Go to World Settings → API Connections. The world’s MCP URL is shown here too.
3. Click Create API Key.
4. Give the key a label — e.g. Claude Desktop on laptop. Labels are how you’ll identify keys later when revoking.
5. Choose a permission:
   • Read-only — the tool can query and search, but cannot make changes.
   • Read-write — the tool can create, update, and delete content.
6. Optionally set an expiry in days. Keys without an expiry never expire automatically, but you can still revoke them anytime.
7. Click Create.

The full key is displayed once, immediately after creation. Copy it now — once you close the dialog, the portal only stores a hash and cannot show the key again.

API keys look like this:

oc_live_a1b2c3d4e5f6...

Limits

• You can hold up to 2 active keys per world.
• Viewers on a world cannot create read-write keys.
• Basic-plan worlds don’t support API keys — connect those by signing in instead. See the plan comparison.

Use a key

Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer oc_live_a1b2c3d4e5f6...

Most MCP clients have a config field where you paste the token (or the full Authorization header). See the client setup guides for the exact field for each tool.

Revoke a key

If a key is exposed, the device holding it is lost, or you stop using the tool:

1. Go to World Settings → API Connections.
2. Find the key by its label.
3. Click Revoke.

Revocation takes effect immediately. The next request from that key fails with 401 Unauthorized.

Rotate a key

There’s no automated rotation yet. To rotate manually:

1. Create a new key with the same permission.
2. Update your AI tool’s config with the new key.
3. Revoke the old key.

Security tips

• Treat API keys like passwords. Don’t commit them to source control or paste them in chat.
• Use read-only keys when the agent doesn’t need to make changes. It’s the cheapest safety net you’ll get.
• Use a separate key per device or tool. If your laptop is lost, you can revoke that one key without disrupting other agents.
• Set an expiry for keys you only need short-term — for a one-off project, a 30- or 60-day expiry is a good default.