Skip to main content
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: 
curl -H "Authorization: metoro_secret_YOUR_API_KEY" \
     https://us-east.metoro.io/api/v1/your-endpoint

​
Example: Fetching logs

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 Roles 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.

​
Support

If you need help with API keys or encounter issues:
  • Contact your organization administrator for permission-related questions
  • Reach out to Metoro Support for technical assistance
  • Check our API status page for service availability
⌘I