API keys

An API key lets the mutagent CLI and the SDK act as you without a browser. Keys start with mg_live_. On your own machine you rarely need to copy one: mutagent login creates and stores a key for you. Create a key by hand for CI, scripts and servers.

Organization key or workspace key

	Organization key	Workspace key
Works in	Every workspace of the organization	One workspace
Choosing the workspace	Per command: `--workspace`, `MUTAGENT_WORKSPACE_ID`, or the saved selection	Fixed by the key
Created at	Settings › Organization › API Keys	Settings › Workspace › API Keys (for the workspace selected in the web app)
`mutagent workspaces current` shows	`Key scope: organization`	`Key scope: workspace`
Use it for	Automation that spans workspaces	CI for one project, where the key must not reach anything else

The key mutagent login stores is an organization key that expires after 30 days. Pick a workspace key when a pipeline should only ever touch one workspace.

Create a key

Open the API keys page

In app.mutagent.io, go to Settings › Organization › API Keys for an organization key, or Settings › Workspace › API Keys for a key limited to the current workspace.

Create it

Click Create Organization API Key (or Create API Key on the workspace page), give it a name, and pick an expiration: Never, 7, 30, 90 or 180 days, or 1 year.

Copy it

The full key is shown once. Store it in your CI secret store or a password manager.

Use a key in CI

Set MUTAGENT_API_KEY and every mutagent command authenticates with it, with no browser and no stored sign-in. With an organization key, also name the workspace:

export MUTAGENT_API_KEY=mg_live_...
export MUTAGENT_WORKSPACE_ID=3f6a2c1e-8b4d-4e0a-9c7f-2d5e8a1b6c90   # organization keys only

mutagent workspaces current --json

Output

{
  "success": true,
  "scope": "organization",
  "organization": {
    "id": "org_Q7mZ2pLx9TnB4vKc_R8wd",
    "name": "acme",
    "slug": "acme"
  },
  "workspace": {
    "id": "3f6a2c1e-8b4d-4e0a-9c7f-2d5e8a1b6c90",
    "name": "support-bots",
    "slug": "support-bots"
  },
  "expiresAt": "2026-12-24T09:00:00.000Z"
}

Exit code 0 means the key works in that workspace. The other exit codes:

Exit code	Code	Fix
2	`AUTH_EXPIRED`, `INVALID_API_KEY`	The key expired, was revoked, or is not a Mutagent key. Create a new one.
3	`WORKSPACE_REQUIRED`	An organization key needs a workspace: set `MUTAGENT_WORKSPACE_ID`, or pass `--workspace <id>`.
1	—	Any other failure. Under `--json`, read `code` and `suggestedAction`. See Errors and exit codes.

To store the key on the machine instead of exporting it in every shell, run MUTAGENT_API_KEY=mg_live_... mutagent login --json once. A GitHub Actions step:

- name: Check the Mutagent workspace
  env:
    MUTAGENT_API_KEY: ${{ secrets.MUTAGENT_API_KEY }}
    MUTAGENT_WORKSPACE_ID: ${{ vars.MUTAGENT_WORKSPACE_ID }}
  run: |
    npm install -g @mutagent/cli
    mutagent providers list --json

CI=true, which most CI systems set, turns off every prompt, the same as --non-interactive. --api-key <key> on a single command works too, but it puts the key in your shell history; prefer the environment variable. The SDK reads the same key:

import { Mutagent } from '@mutagent/sdk';

const client = new Mutagent({
  security: { apiKey: process.env.MUTAGENT_API_KEY! },
});

Revoke a key

Revoke a key on the page where it was created. It stops working on the next request. An expired key stays in the list until you revoke it.

Good practice

One key per pipeline or machine, so revoking one breaks nothing else.
Set an expiration on keys that live in CI.
Prefer a workspace key when the job only needs one workspace.
Never commit a key. If one leaks, revoke it first, then create its replacement.

Overview

Sandbox

Managed agents

Setup

Organization key or workspace key

Create a key

Use a key in CI

Revoke a key

Good practice

​Organization key or workspace key

​Create a key

​Use a key in CI

​Revoke a key

​Good practice

Organization key or workspace key

Create a key

Use a key in CI

Revoke a key

Good practice