API Authentication

API Authentication Overview

The ConductorQA API uses secure API key authentication to control access to your testing data and ensure proper project-level permissions. This guide covers everything you need to know about authenticating with our REST API.

Authentication Method

ConductorQA uses Bearer Token authentication with API keys for secure access to the API endpoints.

Request Format

Include your API key in the Authorization header of every API request:

Authorization: Bearer YOUR_API_KEY_HERE

Example API Request

curl -X GET "https://api.conductorqa.com/v1/projects" \
  -H "Authorization: Bearer cqa_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234"
  -H "Content-Type: application/json"

Getting Your API Key

Step 1: Access API Settings

1. Log in to your ConductorQA account
2. Navigate to Settings → API Keys
3. Click Generate New API Key

Step 2: Configure API Key

1. Name your key: Give it a descriptive name (e.g., “CI/CD Integration”, “Jest Reporter”)
2. Select projects: Choose which projects this key can access
3. Set permissions: Configure read/write access levels
4. Click Create API Key

Step 3: Secure Your Key

⚠️ Important: Your API key will only be shown once. Copy it immediately and store it securely.

API Key Management

Key Properties

• Project-specific access: Each key is scoped to specific projects
• Configurable permissions: Control read/write access per project
• Unique identification: Each key has a unique identifier for tracking
• Revocable: Keys can be disabled or deleted at any time

Best Practices

1. Use descriptive names: Name keys based on their purpose
2. Limit project access: Only grant access to required projects
3. Regular rotation: Rotate keys periodically for security
4. Secure storage: Store keys in environment variables, not in code
5. Monitor usage: Review API key usage in the dashboard

Authentication Examples

JavaScript/Node.js

const API_KEY = process.env.CONDUCTORQA_API_KEY;
const BASE_URL = 'https://api.conductorqa.com/v1';

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

// Get all projects
const response = await fetch(`${BASE_URL}/projects`, { headers });
const projects = await response.json();

Python

import os
import requests

API_KEY = os.getenv('CONDUCTORQA_API_KEY')
BASE_URL = 'https://api.conductorqa.com/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# Get all projects
response = requests.get(f'{BASE_URL}/projects', headers=headers)
projects = response.json()

cURL

# Set your API key as an environment variable
export CONDUCTORQA_API_KEY="cqa_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234"

# Make API requests
curl -X GET "https://api.conductorqa.com/v1/projects" \
  -H "Authorization: Bearer $CONDUCTORQA_API_KEY" \
  -H "Content-Type: application/json"

Project-Level Access Control

Understanding Scopes

API keys are scoped to specific projects, ensuring secure access:

• Full Project Access: Read and write to all test data within allowed projects
• Read-Only Access: View test data but cannot modify or create
• Specific Operations: Future versions will support granular permissions

Project Selection

When creating an API key:

1. Select Projects: Choose which projects the key can access
2. Permission Levels: Set read or read/write access per project
3. Access Validation: API validates project access on every request

Error Handling

Common Authentication Errors

401 Unauthorized

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "code": "INVALID_API_KEY"
}

Causes:

• Missing or malformed API key
• Revoked or expired key
• Incorrect Authorization header format

403 Forbidden

{
  "error": "Insufficient permissions",
  "message": "This API key does not have access to the requested project",
  "code": "PROJECT_ACCESS_DENIED"
}

Causes:

• API key not granted access to the requested project
• Attempting write operations with read-only key

Error Response Format

All authentication errors follow this structure:

{
  "error": "Error type",
  "message": "Human-readable description",
  "code": "ERROR_CODE",
  "timestamp": "2025-08-28T10:30:00Z"
}

Rate Limiting

Current Limits

• 1000 requests per hour per API key
• Rate limit headers included in all responses
• 429 status code when limits exceeded

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1724832600

Security Considerations

API Key Security

1. Environment Variables: Store API keys in environment variables
2. Never Commit Keys: Don’t commit API keys to version control
3. Rotate Regularly: Change API keys periodically
4. Monitor Access: Review API key usage logs
5. Revoke Unused Keys: Remove keys that are no longer needed

Network Security

• HTTPS Only: All API communication must use HTTPS
• Valid Certificates: Verify SSL certificates in production
• Secure Networks: Use API keys only on secure networks

Troubleshooting

Common Issues

API Key Not Working

1. Verify the key format: cqa_live_ prefix
2. Check project access permissions
3. Ensure key hasn’t been revoked
4. Confirm correct Authorization header format

Project Access Denied

1. Verify API key has project access
2. Check project ID in the request
3. Confirm read/write permissions
4. Review project settings

Rate Limit Exceeded

1. Implement request throttling
2. Cache responses when possible
3. Use bulk endpoints for multiple operations
4. Contact support for higher limits

Getting Help

If you’re experiencing authentication issues:

1. Check your API key status in the dashboard
2. Review the error response details
3. Verify project access permissions
4. Contact support with the error details

Next Steps

Now that you understand API authentication:

• Explore API Endpoints - Learn about available API operations
• Test Results Integration - Set up automated test reporting
• Best Practices - Follow recommended integration patterns

Need Help? Check your API key status in the ConductorQA dashboard or contact support for assistance with authentication issues.