Best Practices & Security

Security Best Practices

1. Store Keys Securely

Never commit API keys to version control.

• ❌ Don't: Commit keys to Git repositories
• ❌ Don't: Hardcode keys in source code
• ❌ Don't: Share keys in chat or email
• ✅ Do: Use environment variables
• ✅ Do: Use secret managers (AWS Secrets Manager, HashiCorp Vault, etc.)
• ✅ Do: Store keys in secure configuration files outside version control

2. Use Environment Variables

Store API keys in environment variables:

# .env file (add to .gitignore)
airtasystems_API_KEY=gb_live_your_api_key_here

# Load in your application
import os
api_key = os.getenv('airtasystems_API_KEY')

3. Rotate Keys Regularly

• Create new keys periodically (e.g., every 90 days)
• Revoke old keys after confirming new keys work
• Update integrations to use new keys
• Monitor for any issues during rotation

4. Use IP Restrictions

Limit keys to specific IP addresses when possible:

• Whitelist only the IPs that need access
• Use static IPs for server integrations
• Consider VPN or proxy for dynamic IPs
• Regularly review and update IP whitelists

5. Set Expiration Dates

Use expiration dates for additional security:

• Set expiration for temporary integrations
• Use shorter expirations for higher-risk scenarios
• Plan key rotation before expiration
• Monitor expiration dates and renew as needed

6. Minimal Scopes

Only grant the minimum scopes needed:

• Review what each scope allows
• Grant only necessary permissions
• Use separate keys for different integrations
• Regularly audit and remove unused scopes

7. Monitor Usage

Regularly check key usage:

• Review lastUsedAt timestamps in API Key Management
• Monitor for unexpected usage patterns
• Set up alerts for unusual activity
• Revoke keys that show suspicious activity

Integration Best Practices

Error Handling

Implement robust error handling:

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    data = response.json()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 401:
        # Handle invalid API key
        logger.error("Invalid API key")
    elif e.response.status_code == 403:
        # Handle insufficient scopes or IP restriction
        logger.error("Access denied")
    else:
        # Handle other errors
        logger.error(f"API error: {e}")

Rate Limiting

Implement rate limit handling:

• Check X-RateLimit-Remaining header
• Implement exponential backoff
• Respect rate limit windows
• Cache responses when appropriate

Retry Logic

Implement retry logic for transient failures:

import time

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                time.sleep(wait_time)
            else:
                raise

Key Management Workflow

Creating Keys

1. Go to API Key Management
2. Click Generate API Key
3. Configure name, scopes, IP restrictions, expiration
4. Save the key immediately (shown only once)
5. Store securely in environment variable or secret manager

Rotating Keys

1. Create a new key with same scopes and restrictions
2. Test the new key in a non-production environment
3. Update your integration to use the new key
4. Verify everything works with the new key
5. Revoke the old key

Revoking Keys

1. Identify the key to revoke
2. Verify it's no longer needed
3. Click Revoke in API Key Management
4. Confirm revocation
5. Update any documentation referencing the key

Security Checklist

• ✅ API keys stored in environment variables or secret managers
• ✅ Keys never committed to version control
• ✅ .env files added to .gitignore
• ✅ IP restrictions configured where possible
• ✅ Expiration dates set for temporary integrations
• ✅ Minimal scopes granted
• ✅ Keys rotated regularly
• ✅ Usage monitored regularly
• ✅ Error handling implemented
• ✅ Rate limiting respected

What to Do If a Key Is Compromised

1. Immediately revoke the key in API Key Management
2. Review recent API usage for suspicious activity
3. Create a new key with appropriate scopes
4. Update all integrations to use the new key
5. Review and tighten security practices
6. Consider enabling additional IP restrictions
7. Monitor for any unauthorized access

Additional Resources

• API Keys Overview
• Creating & Managing API Keys
• Authentication & Scopes
• Error Handling & Troubleshooting