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

# API Keys

> Generate API keys for programmatic access to mixus

# API keys

Generate personal API keys to interact with mixus programmatically. Perfect for automation, integrations, and eval tasks.

***

## Overview

mixus API keys allow you to:

* ✅ Create and manage evaluation tasks
* 📊 Track agent execution status
* 🤖 Automate workflows
* 🔗 Integrate with external systems
* 📈 Monitor performance metrics

***

## Generating your first API key

### Step 1: navigate to API keys

1. Sign in to [app.mixus.ai](https://app.mixus.ai)
2. Go to **Integrations** → **mixus API Keys**
3. Click **"Manage API Keys"**

### Step 2: create key

1. Click **"Generate API Key"**
2. Fill in the details:
   * **Name**: Descriptive name (e.g., "Production Eval Key")
   * **Description**: What you'll use this key for
   * **Permissions**: Select the scopes you need
   * **Expiration**: Choose when the key expires
3. Click **"Generate API Key"**

### Step 3: save your key

**⚠️ Important**: The key is shown only once! Copy it immediately and store it securely.

Your key will look like:

```text theme={null}
mxs_eval_A7k2mN9pQx4vZ8wB3cF1dG6hJ5lK0sM
```

***

## Permissions and scopes

Control what your API keys can access:

### Available scopes

| Scope           | What it allows                                              |
| --------------- | ----------------------------------------------------------- |
| **eval:create** | Create and run evaluation agents programmatically           |
| **eval:read**   | View execution status, checkpoints, and performance metrics |
| **eval:manage** | Full access - create, read, update, and delete evals        |

***

## Using your API key

### Basic usage

Include your API key in the `Authorization` header:

```bash theme={null}
curl https://app.mixus.ai/api/endpoint \
  -H "Authorization: Bearer mxs_eval_YOUR_KEY"
```

### Example: create eval task

```bash theme={null}
curl -X POST https://app.mixus.ai/api/eval/create-task-agent \
  -H "Authorization: Bearer mxs_eval_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskName": "Calculate Commission",
    "taskDescription": "Calculate 15% commission on $50,000",
    "autoDetectCheckpoints": true,
    "testMode": "with-verification",
    "assignedReviewer": "you@example.com"
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "executionId": "670abc...",
  "chatUrl": "https://app.mixus.ai/chat/670abc...",
  "checkpointCount": 1
}
```

### Example: check status

```bash theme={null}
curl https://app.mixus.ai/api/eval/status/EXECUTION_ID \
  -H "Authorization: Bearer mxs_eval_YOUR_KEY"
```

***

## Best practices

### Security

✅ **Do:**

* Store keys in environment variables
* Use different keys for dev/production
* Rotate keys regularly (30-90 days)
* Use minimal required permissions
* Revoke compromised keys immediately

❌ **Don't:**

* Commit keys to version control
* Share keys between team members
* Store keys in client-side code
* Use production keys in development

### Example: Secure Storage

```bash theme={null}
# Store in .env file (gitignored)
MIXUS_API_KEY=mxs_eval_your_key_here

# Use in scripts
export MIXUS_API_KEY=$(cat .env | grep MIXUS_API_KEY | cut -d= -f2)
curl https://app.mixus.ai/api/eval/create-task-agent \
  -H "Authorization: Bearer $MIXUS_API_KEY" \
  -d '{...}'
```

***

## Managing your keys

### View active keys

Visit [app.mixus.ai/integrations/api-keys](https://app.mixus.ai/integrations/api-keys) to see:

* All your active keys
* Usage statistics
* Last used date
* Expiration status

### Revoke a key

1. Go to API keys page
2. Find the key you want to revoke
3. Click the trash icon
4. Confirm revocation

**Note**: Revoked keys stop working immediately.

***

## Limitations

* **Maximum keys**: 10 active keys per user
* **Rate limit**: 100 requests per minute per key
* **Concurrent executions**: 10 simultaneous eval tasks
* **Key length**: 41 characters (format: `mxs_eval_[32 chars]`)

***

## Troubleshooting

### "Unauthorized" error

**Problem**: API returns 401 Unauthorized

**Solutions**:

1. Check your API key is correct
2. Verify key hasn't expired
3. Ensure key hasn't been revoked
4. Confirm you have the required scope

### "Access denied" error

**Problem**: API returns 403 Access Denied

**Solution**: Your API key doesn't have the required permission. Generate a new key with the correct scope.

### Key not working

**Problem**: Newly generated key doesn't work

**Solutions**:

1. Wait 5-10 seconds (propagation delay)
2. Check you copied the entire key
3. Verify no extra spaces in the key
4. Ensure you're using the Bearer format

***

## Related documentation

* [Evaluation API](../eval-api) - Complete API reference and examples
* [Agent examples](./examples) - Ready-to-use agent templates
* [Integrations](../integrations/overview) - Connect external services

***

## Support

Need help with API keys?

* 📧 Email: [support@mixus.ai](mailto:support@mixus.ai)
* 📖 Documentation: [Evaluation API guide](../eval-api)
* 💡 Examples: Check the [evaluation API documentation](../eval-api) for working code samples