Skip to content
HomeStar Docs

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?

Section titled “Why API Keys?”

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

Alternative Authentication Methods

Section titled “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

Section titled “Security Model”

Three-Layer Defense

Section titled “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

Section titled “How Keys Are Protected”

During Creation

Section titled “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

Section titled “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

Section titled “Threat Model”

What API Keys Protect Against

Section titled “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

Section titled “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

Section titled “Risk Assessment”

High-Risk Scenarios

Section titled “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

Section titled “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)

Section titled “Security Best Practices (Admin Perspective)”

Key Lifecycle Management

Section titled “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

Section titled “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

Section titled “Comparison to Other Systems”

Stripe API Keys

Section titled “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

Section titled “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

Section titled “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?

Section titled “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

Section titled “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

Section titled “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

Section titled “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
Section titled “Related Documentation”