Overview API Keys in Warrn provide secure programmatic access for automation, CI/CD pipelines, and third-party integrations. The system supports organization-level and service-level keys with granular permissions and comprehensive security features.
API Key Types Organization vs Service Keys Organization Keys
Access to all services within organization
User and team management capabilities
Organization-wide settings and configuration
Ideal for automation and CI/CD
Service Keys
Limited to specific service operations
Fine-grained service permissions
Enhanced security for third-party integrations
Perfect for service-specific monitoring tools
Key Structure interface ApiKey { id : string ; name : string ; key_type : 'organization' | 'service' ; permissions : 'read' | 'write' | 'admin' ; // Security masked_key : string ; // Displayed key (masked) allowed_ips : string []; // IP restrictions expires_at ?: string ; // Optional expiration is_active : boolean ; // Enable/disable status // Usage tracking total_requests : number ; last_used_at ?: string ; last_request_ip ?: string ; // Metadata created_at : string ; created_by_email : string ; organization_id : string ; service_id ?: string ; // For service-level keys }
Permission Levels Permission Types Permission Matrix Security Features IP Address Restrictions Limit API key usage to specific IP addresses or CIDR blocks:
interface IPRestriction { allowed_ips : string []; // ["192.168.1.0/24", "10.0.0.1"] enforce_restrictions : boolean ; allow_organization_ips ?: boolean ; // Allow org's known IPs }
Expiration Management
No Expiration Keys that never expire for long-term automation.
Fixed Date Keys that expire on a specific date for temporary access.
Relative Keys that expire after a certain period (30, 90, 365 days).
Usage Monitoring Real-time tracking of API key usage for security and optimization:
interface UsageMetrics { total_requests : number ; requests_last_24h : number ; requests_last_7d : number ; requests_last_30d : number ; // Geographic data countries_accessed_from : string []; // Endpoint usage most_used_endpoints : { endpoint : string ; count : number ; }[]; // Error rates error_rate_percentage : number ; common_errors : { status_code : number ; count : number ; }[]; }
API Key Management Interface Key Creation Workflow
Basic Information
Define key name, description, and select key type (organization or service).
Permission Assignment
Choose appropriate permission level based on intended use case.
Security Configuration
Set IP restrictions, expiration date, and other security parameters.
Key Generation
System generates secure key and displays it once for secure storage.
Verification
Test the key with a simple API call to ensure proper configuration.
Key Management Table The API keys management interface provides comprehensive key oversight:
Key Information
Name and masked key value
Permission level with visual badges
Key type (organization/service)
Creation date and creator
Usage & Security
Total request count
Last used timestamp
Last access IP address
Active/inactive status
Expiration information
Bulk Operations Bulk operations on API keys should be used carefully as they can affect multiple integrations simultaneously.
Bulk Deactivation : Temporarily disable multiple keysBulk Deletion : Permanently remove unused keysBulk Expiration Update : Extend or modify expiration datesBulk IP Updates : Update IP restrictions across keys
Key Rotation Strategy Automated Rotation // Example: Rotate API key with zero downtime const rotateApiKey = async ( keyId : string ) => { // 1. Create new key with same permissions const newKey = await createApiKey ({ name: ` ${ oldKey . name } (rotated)` , permissions: oldKey . permissions , allowed_ips: oldKey . allowed_ips , key_type: oldKey . key_type }); // 2. Update integrations to use new key await updateIntegrations ( oldKey . id , newKey . id ); // 3. Monitor for successful transition await monitorKeyUsage ( newKey . id , { timeout: 300000 }); // 5 minutes // 4. Deactivate old key after confirmation await deactivateApiKey ( oldKey . id ); // 5. Schedule old key deletion await scheduleKeyDeletion ( oldKey . id , { delay: '7d' }); };
Rotation Best Practices
Integration Examples # Using API key in requests curl -H "Authorization: Bearer your-api-key-here" \ -H "Content-Type: application/json" \ https://api.warrn.io/alerts # Alternative header format curl -H "X-API-Key: your-api-key-here" \ https://api.warrn.io/services
SDK Integration // JavaScript SDK example import { WarrnClient } from '@warrn/sdk' ; const client = new WarrnClient ({ apiKey: process . env . WARRN_API_KEY , baseUrl: 'https://api.warrn.io' }); // Create alert with API key authentication const alert = await client . alerts . create ({ name: 'High CPU Usage' , severity: 'warning' , service_id: 'service-uuid' });
CI/CD Pipeline Integration # GitHub Actions example name : Deploy and Update Status on : push : branches : [ main ] jobs : deploy : runs-on : ubuntu-latest steps : - name : Update deployment status run : | curl -X POST \ -H "Authorization: Bearer ${{ secrets.WARRN_API_KEY }}" \ -H "Content-Type: application/json" \ -d '{"status": "deploying", "message": "Deployment started"}' \ https://api.warrn.io/status-pages/components/api-gateway
Monitoring & Analytics Usage Analytics API key usage can be monitored through comprehensive analytics:
Security Monitoring
Anomaly Detection Automatic detection of unusual usage patterns or potential security threats.
Access Logs Comprehensive logging of all API key usage for audit and compliance.
Rate Limiting Default Limits # Response headers for rate limiting HTTP/1.1 200 OK X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1642789200 X-RateLimit-Retry-After: 3600
Handling Rate Limits // Example: Exponential backoff for rate limiting const makeApiRequest = async ( url , options , retries = 3 ) => { try { const response = await fetch ( url , { ... options , headers: { 'Authorization' : `Bearer ${ apiKey } ` , ... options . headers } }); if ( response . status === 429 ) { const retryAfter = response . headers . get ( 'X-RateLimit-Retry-After' ); const delay = retryAfter ? parseInt ( retryAfter ) * 1000 : Math . pow ( 2 , 4 - retries ) * 1000 ; if ( retries > 0 ) { await new Promise ( resolve => setTimeout ( resolve , delay )); return makeApiRequest ( url , options , retries - 1 ); } } return response ; } catch ( error ) { if ( retries > 0 ) { await new Promise ( resolve => setTimeout ( resolve , 1000 )); return makeApiRequest ( url , options , retries - 1 ); } throw error ; } };
Best Practices Security Guidelines
Principle of Least Privilege
Grant only the minimum permissions required for the intended use case.
Environment Separation
Use different API keys for development, staging, and production environments.
Regular Auditing
Regularly review API key usage and deactivate unused keys.
Secure Storage
Store API keys in secure credential management systems, never in code repositories.
Operational Guidelines Never commit API keys to version control. Use environment variables or secure credential stores.
API Reference Key Management Endpoints # List all API keys GET /api/api-keys # Create new API key POST /api/api-keys { "name" : "Production Monitoring", "key_type" : "organization", "permissions" : "write", "allowed_ips" : [ "10.0.0.0/8" ], "expires_at" : "2024-12-31T23:59:59Z" } # Update API key PATCH /api/api-keys/{id} { "name" : "Updated Key Name", "is_active" : false } # Delete API key DELETE /api/api-keys/{id} # Get key usage statistics GET /api/api-keys/{id}/stats
Usage Endpoints # Get current usage GET /api/api-keys/{id}/usage # Get usage history GET /api/api-keys/{id}/usage/history?period=30d # Get access logs GET /api/api-keys/{id}/logs?limit= 100
See the API Keys API documentation for complete endpoint details and authentication examples. 
