API Key Security

Understanding the security model behind API keys, why they’re used, potential risks, and how the system mitigates threats.

---

Why API Keys?

API keys provide a balance between security and usability for programmatic access.

Alternative Authentication Methods

Method	Pros	Cons	Use Case
API Keys	Simple, stateless, revocable	Static credentials, require careful management	Server-to-server integrations
OAuth 2.0	User-delegated, scoped permissions	Complex flow, requires user interaction	Third-party apps accessing user data
JWT Tokens	Stateless, short-lived, signed	Requires token refresh logic	User session authentication
Basic Auth	Extremely simple	Username/password in every request	Legacy systems only

Why API keys win for this platform:

1. Server-to-server integrations — Most use cases are automated systems (CRMs, analytics tools)
2. Simpler than OAuth — No user authorization flow needed for admin/broker operations
3. Easier to manage — Single revocable token vs. managing user credentials
4. Role-based access — Keys inherit permissions, no per-user configuration

---

Security Model

Three-Layer Defense

1. Authentication

Is this a valid key?

Validates the key exists and hasn’t been revoked

2. Authorization

Does this key have permission?

Checks role-based access control (RBAC)

3. Rate Limiting

Is this usage pattern legitimate?

Prevents abuse and runaway scripts

How Keys Are Protected

During Creation

1. Random 256-bit value generated using CSPRNG
2. Shown to user once in plaintext
3. Hashed using bcrypt (work factor 12)
4. Only hash stored in database

Result: Even database administrators cannot retrieve original keys.

During Authentication

1. Client sends key in X-API-Key header
2. Server hashes the provided key
3. Compares hash to stored hash (constant-time comparison)
4. Validates key is active (not revoked)
5. Loads associated role and permissions

Result: Timing attacks cannot reveal valid keys.

---

Threat Model

What API Keys Protect Against

Unauthorized Access

Only users with valid keys can access the API

Mitigation: Key validation, role-based permissions

Privilege Escalation

Agent keys cannot perform admin operations

Mitigation: Role-based access control (RBAC)

Denial of Service

Runaway scripts can’t exhaust server resources

Mitigation: Rate limiting per key

Data Exfiltration

Limits on how much data can be extracted

Mitigation: Rate limits, audit logging

What API Keys Don’t Protect Against

Threat	Why Keys Don’t Help	Actual Mitigation
Key Theft	Stolen key works like the original	Key rotation, secure storage, monitoring
Insider Threats	Legitimate users with malicious intent	Audit logging, least privilege, separation of duties
Network Sniffing	Keys sent in HTTP headers	HTTPS/TLS encryption (required)
Database Breach	Hashes can be cracked offline	Strong hashing (bcrypt), database encryption

---

Risk Assessment

High-Risk Scenarios

1. Admin Key Exposure

   • Impact: Full system access, data deletion, user creation
   • Likelihood: Medium (human error, git commits, logs)
   • Mitigation: Strict admin key policies, regular rotation, monitoring

2. Credential Stuffing

   • Impact: Compromised keys from other breaches
   • Likelihood: Low (unique random keys, not reused passwords)
   • Mitigation: N/A (API keys not password-based)

3. Rate Limit Bypass

   • Impact: Resource exhaustion, data scraping
   • Likelihood: Low (enforced at application level)
   • Mitigation: Per-key and per-IP rate limiting

Medium-Risk Scenarios

1. Broker Key Misuse

   • Impact: Access to competitors’ brokerage data
   • Likelihood: Low (keys scoped to brokerage)
   • Mitigation: Brokerage isolation in database queries

2. Logging Sensitive Data

   • Impact: Keys exposed in application logs
   • Likelihood: Medium (developer error)
   • Mitigation: Automated log redaction, code review

3. Revoked Key Caching

   • Impact: Brief window where revoked keys still work
   • Likelihood: Low (immediate database check)
   • Mitigation: No caching of key validation

---

Security Best Practices (Admin Perspective)

Key Lifecycle Management

Creation:

• Require justification for admin-level keys
• Set expiration dates for temporary integrations
• Document key purpose in metadata

Usage:

• Monitor request patterns for anomalies
• Alert on unusual error rates (>10%)
• Review last-used timestamps monthly

Rotation:

• Force rotation every 90 days for critical systems
• Provide advance notice to integration owners
• Validate new keys before revoking old ones

Revocation:

• Immediate revocation on suspected compromise
• Grace period (24h) for planned migrations
• Audit log entry with reason for revocation

Monitoring and Alerting

Set up alerts for:

Alert Type	Threshold	Action
High Error Rate	>10% 4xx/5xx responses	Investigate integration issue
Rate Limit Hit	Key hits limit 3+ times/day	Contact integration owner
Geographic Anomaly	Requests from unexpected country	Potential key theft
After-Hours Usage	Activity outside business hours	Review for automation gone wrong
Dormant Key Activity	Unused key suddenly active	Potential compromise

---

Comparison to Other Systems

Stripe API Keys

Similarities:

• Prefixed format (sk_, pk_ vs. idx_)
• Role-based (secret vs. publishable)
• Revocable at any time

Differences:

• Stripe has restricted keys (scoped permissions)
• HomeStar uses role-based, not scope-based

AWS IAM Access Keys

Similarities:

• Paired with secret (Access Key ID + Secret)
• Role-based permissions (IAM policies)

Differences:

• HomeStar uses single-token authentication
• No separate “secret” component
• Simpler rotation process

GitHub Personal Access Tokens

Similarities:

• Fine-grained permissions (scopes)
• Expiration dates

Differences:

• HomeStar uses role-based, not scope-based
• Designed for server-to-server, not user delegation

---

Why Not OAuth 2.0?

OAuth 2.0 is the industry standard for user-delegated API access, but it’s overkill for this platform.

OAuth Complexity

sequenceDiagram
    User->>App: Clicks "Connect to CRM"
    App->>OAuth Server: Authorization request
    OAuth Server->>User: Login & grant permissions
    User->>OAuth Server: Approves
    OAuth Server->>App: Authorization code
    App->>OAuth Server: Exchange code for token
    OAuth Server->>App: Access token
    App->>API: Request with token

API Key Simplicity

sequenceDiagram
    Admin->>Dashboard: Create API key
    Dashboard->>Admin: Returns key
    Admin->>Integration: Configures key
    Integration->>API: Request with key

When OAuth would be better:

• Third-party apps accessing user data
• Granular permissions per integration
• User-initiated access revocation

Why API keys suffice:

• Admin-controlled integrations (no user delegation)
• Role-based permissions are sufficient
• Simpler for server-to-server automation

---

Future Security Enhancements

Potential improvements to the key system:

1. IP Whitelisting — Restrict keys to specific IP ranges
2. Scoped Permissions — Agent keys with read-only property access
3. Key Expiration — Enforce automatic expiration dates
4. Multi-Factor Authentication — Require 2FA for admin key creation
5. Anomaly Detection — Machine learning to identify suspicious patterns
6. Mutual TLS — Certificate-based authentication for high-security integrations

---

Related Documentation

• Manage API Keys — Creating and revoking keys
• API Key Reference — Technical specifications