> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Create and manage API keys for authentication

# 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

<Steps>
  <Step title="Open Dashboard">
    Navigate to [app.mutagent.io/settings/api-keys](https://app.mutagent.io/settings/api-keys)
  </Step>

  <Step title="Go to Settings">
    Click **Settings** → **API Keys**
  </Step>

  <Step title="Create Key">
    Click **Create API Key** and configure:

    * **Name**: Descriptive name (e.g., "Production Server")
    * **Scope**: Workspace, Organization, or User
    * **Permissions**: Select required permissions
  </Step>

  <Step title="Copy Key">
    Copy and securely store your key -- it will not be shown again. The key starts with `mt_`.
  </Step>
</Steps>

## Key Scopes

| Scope            | Access Level               | Headers Required                       | Use Case                                            |
| ---------------- | -------------------------- | -------------------------------------- | --------------------------------------------------- |
| **Workspace**    | All workspace resources    | None (auto-inferred)                   | Team projects, shared prompts (recommended for CLI) |
| **Organization** | All org resources          | `x-workspace-id` required              | Cross-workspace access                              |
| **User**         | Your resources across orgs | `x-workspace-id` + `x-organization-id` | Admin tools, personal development                   |

<Tip>
  Workspace-scoped keys are recommended for most use cases. They require zero additional configuration -- the workspace and organization are inferred automatically from the key.
</Tip>

## Using API Keys

### Environment Variables (Recommended)

```bash theme={null}
# .env
MUTAGENT_API_KEY=mt_xxxxxxxxxxxx
```

### CLI Authentication

```bash theme={null}
# 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

```typescript theme={null}
import { Mutagent } from '@mutagent/sdk';

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

### Tracing Configuration

The tracing module reads `MUTAGENT_API_KEY` automatically, or you can pass the key explicitly:

```typescript theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
mutagent config set workspace <workspace-id>
mutagent config set org <organization-id>
```

## Security Best Practices

<Warning>
  Never commit API keys to version control or expose them in client-side code.
</Warning>

<AccordionGroup>
  <Accordion title="Use environment variables">
    Store keys in `.env` files and load with `dotenv` or your framework's config system. Add `.env` to your `.gitignore`.
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Create new keys periodically and revoke old ones from the dashboard.
  </Accordion>

  <Accordion title="Use workspace-scoped keys">
    Workspace-scoped keys are the most restrictive scope that still works without additional headers. Use them unless you need cross-workspace access.
  </Accordion>

  <Accordion title="Monitor usage">
    Review API key usage in the dashboard to detect anomalies.
  </Accordion>
</AccordionGroup>