# API Keys

Account-scoped bearer tokens for the REST API and MCP server. Pick scopes, restrict to specific projects, revoke when no longer needed.

API keys are account-level bearer tokens for the REST API and the MCP server. Pick the scopes a script needs, restrict it to specific projects if you want, and revoke when the script is retired.

The project key in your install snippet identifies a project to the SDK and the tracking endpoints. API keys are different — they're for everything else: REST API calls from your backend, CI scripts that read or modify tests, and the MCP server for AI assistants. You only need API keys if you're automating Otter from code.

Manage keys under *Settings → API & MCP*. The page has a creation form, a list of existing keys (with prefixes so you can identify them) and a Revoke button on each. Owners and admins can manage keys; members and viewers can't see this page.

## Creating a key

1. **Name it.** Give it a clear name — like "CI pipeline" or "Claude desktop". The name shows up in the Existing Keys list and helps future-you remember which automation owns the key.
2. **Pick environment.** Live for production automations, Test for local development or staging tools. The token prefix is `oab_live_` or `oab_test_` accordingly. It's an organizational label today, not a behavioral switch.
3. **Pick scopes.** Check only what the script needs. Narrower keys are safer if one ever leaks. See the table below for what each scope covers.
4. **Optionally restrict to projects.** Leave Project Access unchecked for an all-projects key. Check specific projects to limit the key to those — useful for per-site CI pipelines.
5. **Copy the token.** After you submit, the full token appears once under *Copy This Token Now*. Paste it into your secrets manager immediately — the dashboard won't show the full secret again.

## Available scopes

| Scope | What it covers |
| --- | --- |
| `projects:read` | List projects and read project settings. |
| `projects:write` | Create, update, and delete projects. |
| `experiments:read` | List tests, read variants, goals, and configuration. |
| `experiments:write` | Create, update, and delete tests, variants, and goals. |
| `results:read` | Fetch test results, statistics, and per-variant numbers. |
| `account:read` | Read account-level metadata (plan, members, branding). |
| `api_keys:write` | Create and revoke other API keys via the REST API. |
| `sdk:write` | Server-side calls to the same endpoints the browser SDK uses (init, track, convert). |

## Revoking a key

Open *Settings → API & MCP*, find the key in the Existing Keys list, and click Revoke. The key stops working immediately — any script using it will start getting authentication errors. The revoked key stays in the list with a Revoked badge so you have a record of what was issued and when it was retired. Revoking is one-way; to restore access, create a new key.

> **Note: Keeping keys safe**
>
> - **Store keys in a secrets manager.** 1Password, Doppler, your CI's encrypted environment variables — never in a public repo or chat message. Treat them like passwords.
> - **One key per automation.** Each script, runner, or assistant gets its own named key. That way, revoking one doesn't break the others, and the activity trail tells you who used what.
> - **Use the narrowest scopes that work.** A read-only reporting script doesn't need `experiments:write`. If a script only fetches results, give it only `results:read`.
> - **Rotate when in doubt.** If you suspect a key has leaked — even uncertainly — revoke it and issue a new one. The cost is minutes of script re-configuration; the cost of a compromised key is much higher.

## Frequently asked questions

### How is an API key different from the project key in my snippet?

Two different things. The project key (the one in your install snippet, like a short string of letters and numbers) is what the browser SDK and server-side tracking endpoints use to identify which project a visitor or event belongs to. An API key is an account-level bearer token (starts with oab_live_ or oab_test_) for the REST API and the MCP server — anything that needs to read or modify your account's data programmatically. You'll only need API keys if you're scripting against Otter or hooking up an AI assistant.

### Where do I create one?

Settings → API & MCP. Click Create API Key, give it a name, pick the environment (Live or Test), choose the scopes it needs, optionally restrict it to specific projects, and submit. You'll see Copy This Token Now once — copy it into your secrets manager immediately; the full token isn't shown again.

### What's the difference between Live and Test keys?

Today they're the same except for the prefix on the token (oab_live_ vs oab_test_) — it's an organizational label, not a behavioral switch. Use a Test key for local development or staging tooling so you can revoke it without disrupting production scripts. Live keys are for production automations.

### What do the scopes mean?

Each scope is a permission boundary. projects:read and projects:write cover listing and modifying projects; experiments:read and experiments:write cover reading and editing tests; results:read covers fetching test results and statistics; account:read covers account-level metadata; api_keys:write lets a key manage other keys; sdk:write covers the same endpoints the browser SDK uses (for server-side tracking). Pick only what the script needs — narrower keys are safer if one ever leaks.

### What does Project Access do?

By default, an API key works across every project in your account. Use Project Access to restrict a key to one or more specific projects — useful when a script should only ever touch a single project, like a CI pipeline tied to one site. Leaving every project unselected means “all projects.”

### Who can create or revoke API keys?

Owners and admins only. Members and viewers can't see the create form or the revoke buttons. If you need a teammate to manage keys, promote them to admin first.

### What happens when I revoke a key?

It stops working immediately. Any script or assistant using it will start getting authentication errors. Revoking is one-way — there's no “un-revoke” — so if you revoke by mistake, you'll need to create a new key. Revoked keys stay in the list with a Revoked badge so you have an audit trail.

### I lost my token. Can I see it again?

No. The full token is only shown once at creation. The dashboard remembers the prefix so you can identify which key is which, but the full secret can't be recovered. If you've lost a key, create a new one and revoke the old one to keep the audit trail clean.

### Can I use the same key for the MCP server and the REST API?

Yes. The same key works for both — the MCP server and the REST API share the same authentication. You can also use a key in your terminal scripts, CI runners, and AI assistants without needing separate credentials per surface.

### Best practices for keeping keys safe?

Treat them like passwords: store them in a secrets manager (1Password, Doppler, your CI's encrypted variables — never in a public repo). Give each automation its own named key so revoking one doesn't break the others. Use the narrowest scopes that work. Revoke keys you're no longer using. And if you suspect a key has leaked, revoke it immediately and create a new one.

---

Canonical page: https://www.otterab.com/docs/developer-reference/api-keys