Skip to main content

​
API Keys

API keys authenticate your applications with MutagenT. All API keys use the mt_ prefix. Learn how to create, manage, and securely use them.

​
Creating API Keys

1

Open Dashboard

Navigate to app.mutagent.io/settings/api-keys
2

Go to Settings

Click Settings → API Keys
3

Create Key

Click Create API Key and configure:
  • Name: Descriptive name (e.g., “Production Server”)
  • Scope: Workspace, Organization, or User
  • Permissions: Select required permissions
4

Copy Key

Copy and securely store your key — it will not be shown again. The key starts with mt_.

​
Key Scopes

ScopeAccess LevelHeaders RequiredUse Case
WorkspaceAll workspace resourcesNone (auto-inferred)Team projects, shared prompts (recommended for CLI)
OrganizationAll org resourcesx-workspace-id requiredCross-workspace access
UserYour resources across orgsx-workspace-id + x-organization-idAdmin tools, personal development
Workspace-scoped keys are recommended for most use cases. They require zero additional configuration — the workspace and organization are inferred automatically from the key.

​
Using API Keys

# .env
MUTAGENT_API_KEY=mt_xxxxxxxxxxxx

​
CLI Authentication

# Interactive login (opens browser or paste key)
mutagent auth login

# Or set the environment variable (no login needed)
export MUTAGENT_API_KEY=mt_xxxxxxxxxxxx

​
SDK Configuration

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

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

​
Tracing Configuration

The tracing module reads MUTAGENT_API_KEY automatically, or you can pass the key explicitly: 
import { initTracing } from '@mutagent/sdk/tracing';

// Explicit initialization
initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });

// Or just set MUTAGENT_API_KEY in your environment --
// tracing initializes lazily on first span

​
HTTP Headers

For direct API calls: 
curl -H "x-api-key: mt_xxxxxxxxxxxx" \
  https://api.mutagent.io/api/prompts

​
Workspace and Org Defaults

If you use an organization-scoped or user-scoped key, set defaults with the CLI: 
mutagent config set workspace <workspace-id>
mutagent config set org <organization-id>

​
Security Best Practices

Never commit API keys to version control or expose them in client-side code.
Store keys in .env files and load with dotenv or your framework’s config system. Add .env to your .gitignore.
Create new keys periodically and revoke old ones from the dashboard.
Workspace-scoped keys are the most restrictive scope that still works without additional headers. Use them unless you need cross-workspace access.
Review API key usage in the dashboard to detect anomalies.