API Token Management Best Practices: Security and Rotation Strategies

API tokens are the keys to your HireSquire account. Proper management is critical for security, cost control, and system reliability. This guide covers security best practices, rotation strategies, and advanced token management features.

Token Types

HireSquire provides two types of API tokens for different use cases:

Environment Variables: The Safe Way

Always use environment variables for token storage. Never hardcode tokens in your source code.

# .env file (never commit this!)
HIRESQUIRE_API_TOKEN=hs_abc123def456...
HIRESQUIRE_WEBHOOK_SECRET=whsec_789ghi...

# Load in Python
import os
from dotenv import load_dotenv
load_dotenv()

client = HireSquire(os.getenv("HIRESQUIRE_API_TOKEN"))

# Load in Node.js
require('dotenv').config();
const client = new HireSquire(process.env.HIRESQUIRE_API_TOKEN);

Agent API Keys: For Production Systems

For AI agents and automated systems, always use Agent API Keys with built-in spend limits:

# Create agent key with daily spend limit
hiresquire agent-keys --action create \
  --name "LangChain Recruiting Agent" \
  --daily-limit 5.00 \
  --monthly-limit 100.00 \
  --permissions "read,screen,email"

# List all keys
hiresquire agent-keys --action list

# View usage statistics
hiresquire agent-keys --action usage --id 123

# Revoke compromised key
hiresquire agent-keys --action revoke --id 123

Spend Limit Features:

• Daily limit: Maximum dollars per calendar day
• Monthly limit: Maximum dollars per calendar month
• Lifetime limit: Total dollars allowed for this key
• Threshold alerts: Webhook notifications at 80% usage

Token Rotation Strategy

Regular token rotation limits exposure if a token is compromised. Follow this schedule:

Graceful Rotation Process:

1. Create new token with identical permissions
2. Update applications to use new token
3. Verify all systems are working with new token
4. Set old token to expire in 7 days
5. Monitor for any usage of old token
6. After 7 days, permanently revoke old token

Common Anti-Patterns to Avoid

Leak Detection and Response

If you suspect a token has been compromised:

CLI Commands for Incident Response:

# Immediately revoke compromised key
hiresquire agent-keys --action revoke --id 123

# Regenerate a key (creates new key value, revokes old one)
hiresquire agent-keys --action regenerate --id 123

# Update spend limits for an existing key
hiresquire agent-keys --action update --id 123 --daily-limit 10.00

Advanced Security Features

Use the update action to adjust permissions or spend limits on the fly:

hiresquire agent-keys --action update \
  --id 123 \
  --monthly-limit 500.00 \
  --permissions "read,screen"

Webhook Signature Verification

Always verify webhook signatures to prevent spoofing:

def verify_webhook_signature(request_body, signature_header, timestamp):
    secret = os.getenv("HIRESQUIRE_WEBHOOK_SECRET")
    signature_string = f"{timestamp}.{request_body}"
    
    expected_signature = hmac.new(
        secret.encode(),
        signature_string.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(
        f"sha256={expected_signature}",
        signature_header
    )

Organization Best Practices

• Principle of Least Privilege: Use Agent Keys with minimum required permissions
• One Token Per Service: Different tokens for different applications or environments
• Audit Logs: Regularly review token usage and access patterns
• Training: Ensure all developers understand token security
• Automation: Use secret management tools instead of manual handling

Recommended Tools

Next Steps

Secure your HireSquire integration:

• REST API Reference - Complete API documentation
• Webhook Security - Webhook signature verification
• FAQ - Security questions answered
• Dashboard - Manage your API tokens

Proper API token management is the foundation of secure hiring automation. By following these best practices, you can protect your account, control costs, and build reliable production systems.