Team & Settings

API Keys

API keys give machines — CI/CD pipelines, the CLI, and AI agents via MCP — access to your organization without a browser login. Each key carries its own set of permissions and can be restricted to a single project, so you can grant exactly the access an integration needs and nothing more.

API keys live under Settings → API Keys. Managing them requires the org:manage-security permission (Admins and Owners), and creating a key requires that your own email address is verified.

Creating an API key

  1. Click Create Key.
  2. Enter a Name that identifies the integration (e.g. "GitHub Actions CI").
  3. Choose an Expiration: Never, 30 days, 60 days, 90 days, 180 days, or 1 year.
  4. Configure Permissions (see below).
  5. Click Create Key.

The full key is displayed once, immediately after creation — copy it and store it securely (a CI secret, a password manager, an environment variable). It will not be shown again; if you lose it, revoke the key and create a new one.

Keys start with the rb_live_ prefix. In the key list, only this short prefix is shown — never the full key.

Permissions and project restriction

Every key is either full-access or scoped:

  • Full Access — the default: unrestricted access to all permissions and projects.
  • Granular scopes — turn the Full Access switch off and tick individual permissions, grouped by area: Projects, API Specs, Testing, Security, Mock Server, Documentation, Monitoring, Notifications, Billing, and Organization. These are the same permissions used by roles — e.g. specs:read, tests:execute, docs:manage-portal.

For each selected permission you can additionally choose All Projects or restrict it to a single project. A key scoped to one project cannot touch the rest of your organization, no matter what the caller asks it to do.

A scoped key needs at least one permission selected.

The scope editor with the Full Access switch off and per-permission project restriction

Grant the least privilege that gets the job done — start read-only and add write scopes only when the integration actually needs them.

Managing existing keys

The key list shows each active key's name, prefix, creation date, expiry date (if set), and when it was last used. From a key's ⋯ menu:

  • Edit Permissions — change the key's scopes at any time without re-issuing it. Switch between Full Access and granular scopes, add or remove permissions, and adjust project restrictions. Changes take effect immediately.
  • Revoke — permanently disables the key. Any applications or pipelines using it immediately lose access. This cannot be undone.

Revoked keys move to a separate Revoked Keys list so you keep an audit trail of what existed.

The API Keys list with active and revoked keys

Where API keys authenticate

An API key authenticates against the same API surface in two ways:

  • REST API — send the key as an X-API-Key header on requests to https://api.routebase.dev.
  • MCP (AI agents) — the Routebase MCP server accepts the same header on https://mcp.routebase.dev, or you can set the ROUTEBASE_API_KEY environment variable when using the stdio CLI. Tool discovery and every tool call are checked against the key's scopes. See MCP Authentication and the MCP Quickstart.

Good hygiene

  • Never commit keys — keep them in CI secrets or environment variables.
  • Set an expiry where your workflow allows it, and rotate keys regularly.
  • One key per integration — so revoking one doesn't break the others, and "last used" tells you what's still alive.
  • Revoke immediately if a key is exposed, then create a replacement.