Skip to main content

​
Overview

Warrn API keys provide secure, organization-level access for automation, CI/CD pipelines, and third-party integrations. Each API key is scoped to your organization and can be configured with specific permissions and security restrictions.
API keys are only displayed once during creation for security reasons. Make sure to copy and store them securely immediately after creation.

​
Creating an API Key

​
Step 1: Navigate to API Keys

  1. Sign in to your Warrn dashboard
  2. Go to Settings → API Keys
  3. Click Create API Key

​
Step 2: Configure Your API Key

API Key Name: Give your key a descriptive name (e.g., “Production Automation”, “CI/CD Pipeline”)Key Type: Currently supports organization level keys (service-level keys coming soon)
Choose the appropriate permission level for your use case:
  • Read: View organization data (alerts, services, teams)
  • Write: Read permissions + create/update resources (recommended for automation)
  • Admin: Write permissions + manage API keys and organization settings
Expiration Date (Optional): Set an expiration date for automatic key rotationIP Restrictions (Optional): Limit access to specific IP addresses or ranges
  • Enter one IP per line: 192.168.1.100
  • Use CIDR notation for ranges: 192.168.1.0/24
  • Leave empty to allow access from any IP

​
Step 3: Secure Your Key

After clicking Create API Key:
  1. Copy the key immediately - it will look like warrn_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abcdef
  2. Store it securely in your password manager or environment variables
  3. Click Done - the key will never be displayed again
Use environment variables to store your API key:
export WARRN_API_KEY="warrn_your_api_key_here"

​
Using API Keys

​
Authentication Header

Include your API key in the X-API-Key header for all requests: 
curl -H "X-API-Key: warrn_your_api_key_here" \
     -H "Content-Type: application/json" \
     https://api.warrn.io/api/alerts/

​
Rate Limits

All API keys have a default rate limit of 1,000 requests per hour. Rate limits are automatically managed for security and fair usage.

​
Managing API Keys

​
Viewing API Keys

The API keys table shows:
  • Name & Masked Key: Descriptive name and masked version (warrn_wo********)
  • Permissions: Current permission level
  • Usage: Request count and last used date/IP
  • Status: Active, inactive, or expired

​
Editing API Keys

You can update:
  • ✅ API key name
  • ✅ Permission level
  • ✅ IP restrictions
  • ✅ Expiration date
  • ✅ Active/inactive status
The actual API key value cannot be changed. Create a new key if you need a different key value.

​
Deleting API Keys

Deleting an API key immediately revokes access. Any applications using the key will stop working instantly.
To delete an API key:
  1. Click the Delete button (trash icon) next to the key
  2. Confirm the deletion in the dialog
  3. Update any applications using the deleted key

​
Security Best Practices

  • Never commit API keys to version control
  • Use environment variables or secure secret management
  • Rotate keys regularly (set expiration dates)
  • Use different keys for different environments (dev/staging/prod)
  • Use the minimum required permissions for each use case
  • Prefer Write over Admin permissions when possible
  • Create separate keys for different applications or teams
  • Restrict IP access when possible
  • Use HTTPS only for API requests
  • Monitor usage patterns for anomalies
  • Regularly review API key usage in the dashboard
  • Set up alerts for suspicious activity
  • Disable unused keys immediately

​
Troubleshooting

Causes:
  • Invalid or expired API key
  • Missing X-API-Key header
  • Key has been deleted or deactivated
Solutions:
  • Verify the key value is correct
  • Check the key is still active in the dashboard
  • Ensure proper header format: X-API-Key: warrn_...
Causes:
  • Insufficient permissions for the requested action
  • IP address not in allowed list
  • Rate limit exceeded
Solutions:
  • Check the key has required permissions (read/write/admin)
  • Verify your IP is in the allowed list
  • Wait for rate limit reset or contact support
Common issues:
  • Typos in the key value
  • Using a masked key instead of the full key
  • Key has expired
  • Wrong API endpoint URL
Solutions:
  • Double-check the full key value (starts with warrn_)
  • Verify the key hasn’t expired
  • Ensure you’re using the correct API base URL

​
Next Steps

Now that you have an API key, you can:

Alerts API

Create and manage alerts programmatically

API Reference

Explore all available API endpoints