API Authentication

The CallMeter API provides programmatic access to your organization's testing infrastructure. All API requests must be authenticated using an API key. This guide covers key creation, usage, scoping, rotation, and security practices.

API Key Format

CallMeter API keys use the cmk_ prefix followed by a cryptographically random string:

cmk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

The cmk_ prefix makes it easy to identify CallMeter keys in your codebase, CI/CD configurations, and secret management systems. It also enables automated scanning tools to detect accidentally committed keys.

Creating an API Key

Only members with the Editor, Admin, or Owner role can create API keys.

1. Open your project in CallMeter, then click API Keys in the left sidebar
2. Click Generate New Key
3. Enter a descriptive name for the key (e.g., "CI/CD Pipeline", "Monitoring Script", "Staging Tests")
4. Review the permissions summary -- the key inherits your current role's permissions
5. Click Create
6. Copy the key immediately -- it will not be shown again
7. Store the key in a secure location (environment variable, secrets manager, CI/CD vault)

Key Naming Best Practices

Use descriptive names that identify the purpose and context of each key:

• github-actions-production -- For production deployment pipeline
• gitlab-ci-staging -- For staging environment tests
• monitoring-cron-job -- For scheduled monitoring scripts
• dev-local-testing -- For development machine API access

Clear naming makes it easy to identify which key to revoke when a system is decommissioned or a team member leaves.

Key Scoping and Permissions

API keys inherit the permissions of the user who created them at the time of creation.

A key created by a Tester can trigger test runs and read results but cannot create or modify test configurations. A key created by an Editor can create and manage resources but cannot invite members or access billing.

Organization Scope

API keys are scoped to the organization of the creating user. A key can only access resources within that organization. If you belong to multiple organizations, create separate keys for each.

Using API Keys in Requests

Include the API key in the Authorization header using the Bearer token scheme.

HTTP Header Format

Authorization: Bearer cmk_your_api_key_here

Example: List Projects

curl -s \
  -H "Authorization: Bearer $CALLMETER_API_KEY" \
  https://callmeter.io/api/v1/projects

Example: Trigger a Test Run

curl -s -X POST \
  -H "Authorization: Bearer $CALLMETER_API_KEY" \
  https://callmeter.io/api/v1/projects/{projectId}/tests/{testId}/run

Example: Get Test Run Results

curl -s \
  -H "Authorization: Bearer $CALLMETER_API_KEY" \
  https://callmeter.io/api/v1/projects/{projectId}/test-runs/{testRunId}

Example: Get Test Run Endpoints

curl -s \
  -H "Authorization: Bearer $CALLMETER_API_KEY" \
  https://callmeter.io/api/v1/projects/{projectId}/test-runs/{testRunId}/endpoints

Authentication Errors

The API returns standard HTTP status codes for authentication failures:

Common Mistakes

Missing Bearer prefix:

# Wrong -- missing "Bearer"
curl -H "Authorization: cmk_abc123..." https://callmeter.io/api/v1/projects

# Correct
curl -H "Authorization: Bearer cmk_abc123..." https://callmeter.io/api/v1/projects

Using the wrong header name:

# Wrong -- X-API-Key is not supported
curl -H "X-API-Key: cmk_abc123..." https://callmeter.io/api/v1/projects

# Correct -- use Authorization header
curl -H "Authorization: Bearer cmk_abc123..." https://callmeter.io/api/v1/projects

Rate Limits

API requests are rate-limited to protect the platform and ensure fair usage. Rate limits are applied per API key.

When you exceed the rate limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying. Implement exponential backoff in your automation scripts to handle rate limiting gracefully.

Key Rotation

Regularly rotating API keys is a security best practice. To rotate a key:

1. Create a new API key with the same permissions
2. Update all systems using the old key to use the new key
3. Verify that all systems work with the new key
4. Revoke the old key

Recommended Rotation Schedule

Revoking API Keys

Revoke a key when it is no longer needed, may be compromised, or belongs to a former team member.

1. Open your project in CallMeter, then click API Keys in the left sidebar
2. Find the key to revoke (identified by its name and creation date)
3. Click Revoke
4. Confirm the revocation

Revoked keys stop working immediately. Any API requests using the revoked key will receive 401 Unauthorized responses. Revocation cannot be undone -- if you need the same access, create a new key.

When to Revoke Keys Immediately

• A team member with API key access leaves the organization
• A key is accidentally committed to a public repository
• You detect unexpected API activity in your audit logs
• A CI/CD system using the key is decommissioned

Security Best Practices

Store Keys Securely

• Environment variables -- export CALLMETER_API_KEY=cmk_... in your shell profile or CI/CD secrets
• Secret managers -- AWS Secrets Manager, HashiCorp Vault, Google Secret Manager
• CI/CD vaults -- GitHub Secrets, GitLab CI Variables, Azure Key Vault

Never Commit Keys to Version Control

Add patterns to your .gitignore to prevent accidental commits:

# Environment files that may contain API keys
.env
.env.local
.env.production

Use secret scanning tools (GitHub secret scanning, GitGuardian, TruffleHog) to detect accidentally committed keys.

Use Separate Keys per Environment

Maintain different API keys for different environments:

• One key for production CI/CD
• One key for staging CI/CD
• One key for local development
• One key for monitoring scripts

This limits the blast radius if any single key is compromised and makes it easier to rotate keys for specific systems.

Audit Key Usage

Periodically review your active API keys:

1. Open your project in CallMeter, then click API Keys in the left sidebar
2. Review the list of active keys
3. Check the last used date for each key
4. Revoke keys that have not been used recently
5. Verify that key names still match their actual usage

Next Steps

• API Endpoints -- Available API operations
• CI/CD Integration -- Use API keys in deployment pipelines
• Roles and Permissions -- Understand how roles affect key permissions