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

# API Keys

> Learn how to create and manage API keys for programmatic access to the Metoro platform

API keys provide secure programmatic access to the Metoro platform, allowing you to integrate Metoro's capabilities into your automated workflows, CI/CD pipelines, and custom applications.

## Overview

API keys are authentication tokens that allow applications to access Metoro's API without requiring user credentials. Each API key:

* Is associated with specific roles and permissions
* Has a configurable expiration date for enhanced security
* Can be revoked at any time
* Is tied to a service user account within your organization

## Creating API Keys

To create a new API key:

1. Navigate to **Settings** → **Developer** → **API Keys**
2. Click the **Create API Key** button
3. Configure your API key:
   * **Name**: Provide a descriptive name (e.g., "Production CI/CD Pipeline")
   * **Roles**: Select one or more roles to define the permissions for this key
   * **Expiration**: Choose an expiration period (30 days, 60 days, 90 days, 180 days, or 1 year)
4. Click **Create API Key**
5. **Important**: Copy and securely store the generated token. You won't be able to view it again after closing the dialog.

### API Key Format

API keys follow the format: `metoro_secret_<random_token>`

Example: `metoro_secret_YWJjZGVmZ2hpams...`

## Using API Keys

Include your API key in the `Authorization` header when making requests to the Metoro API:

```bash theme={null}
curl -H "Authorization: metoro_secret_YOUR_API_KEY" \
     https://us-east.metoro.io/api/v1/your-endpoint
```

### Example: Fetching logs

```bash theme={null}
curl --request POST \
  --url https://us-east.metoro.io/api/v1/query/logs \
  --header 'Authorization: metoro_secret_YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "count(logs{log_level=\"error\", service.name=\"/k8s/default/redis-test-app\"})",
  "startTime": 1750147200000,
  "endTime": 1750150800000,
  "limit": 1000
}'
```

## Managing API Keys

### Viewing API Keys

The API Keys section displays all active keys with:

* **Name**: The descriptive name you provided
* **Roles**: Assigned permissions
* **Created**: When the key was created
* **Created By**: The user who created the key
* **Last Used**: Most recent API call using this key
* **Expires**: Expiration date of the key

### Revoking API Keys

To revoke an API key:

1. Navigate to **Settings** → **Developer** → **API Keys**
2. Find the key you want to revoke
3. Click the delete button (trash icon) in the Actions column
4. Confirm the deletion

**Note**: Revoking a key immediately invalidates it. Any applications using the revoked key will lose access.

## Security Best Practices

### Key Management

* **Use descriptive names**: Make it clear what each key is used for
* **Assign minimal permissions**: Only grant the roles necessary for the specific use case
* **Set expiration dates**: All keys must have an expiration date (maximum 1 year)
* **Rotate regularly**: Create new keys and update your applications before old keys expire
* **Monitor usage**: Review the "Last Used" timestamp to identify unused keys

### Storage and Handling

* **Never commit to version control**: Store API keys in environment variables or secure secret management systems
* **Use different keys for different environments**: Separate keys for development, staging, and production
* **Encrypt in transit**: Always use HTTPS when making API calls
* **Limit key exposure**: Only share keys with team members who need them

## Permissions and Roles

API keys inherit permissions from the roles assigned during creation. The key can only perform actions allowed by its assigned roles.

Common role assignments for API keys:

* **Read-Only Access**: For monitoring dashboards and reporting tools
* **Metrics Writer**: For applications that push custom metrics
* **Alert Manager**: For automation that manages alerts and incidents
* **Full Access**: For CI/CD pipelines that need comprehensive access

See [Access Control (RBAC)](/docs/user-management/rbac) for more information about available roles and permissions.

## Rate Limiting

API keys are subject to rate limiting to ensure platform stability:

* **Default limit**: 1000 requests per minute
* **Burst capacity**: 100 requests per second
* **Response headers**: Include rate limit information

## Troubleshooting

### Invalid API Key

If you receive a `401 Unauthorized` error:

1. Verify the key is correctly formatted with the `metoro_secret_` prefix
2. Check if the key has expired
3. Ensure the key hasn't been revoked
4. Confirm you're using the correct Authorization header format

### Insufficient Permissions

If you receive a `403 Forbidden` error:

1. Review the roles assigned to your API key
2. Verify the operation requires permissions your key has
3. Consider creating a new key with appropriate roles

### Expired Keys

Expired keys return a `401 Unauthorized` error. To resolve:

1. Create a new API key with appropriate permissions
2. Update your application with the new key
3. Delete the expired key from the dashboard

## API Reference

For detailed API documentation and available endpoints, see the [API Reference](/docs/api-reference).

## Support

If you need help with API keys or encounter issues:

* Contact your organization administrator for permission-related questions
* Reach out to [Metoro Support](mailto:support@metoro.io) for technical assistance
* Check our [API status page](https://status.metoro.io) for service availability