Security Considerations

Essential security patterns for integrating with the Starship Rewards API. This guide covers API key management, signing secret rotation, secure credential storage, and network security.

Credential Inventory

Each API credential consists of three values. Understand what each protects:

Secure Credential Storage

Environment Variables (Recommended)

# .env (never commit this file)
STARSHIP_API_KEY=sk_live_abc123def456
STARSHIP_API_SECRET=your-api-secret
STARSHIP_SIGNING_SECRET=whsec_your_signing_secret

Secrets Managers

For production deployments, use a dedicated secrets manager:

What NOT to Do

• Never commit credentials to version control
• Never log API secrets or signing secrets (even at debug level)
• Never embed credentials in client-side code (JavaScript, mobile apps)
• Never share credentials over email, Slack, or other unencrypted channels
• Never use the same credential across environments (use sk_test_* for staging)

Key Rotation Strategy

API Key + Secret Rotation

Rotate API credentials quarterly, or immediately if compromised:

1. Generate new credentials in the Client Portal (Settings → API Keys → Generate)
2. Test the new credentials against your staging environment
3. Deploy the new credentials to production
4. Verify production requests succeed with new credentials
5. Revoke the old credentials

# Step 5: Revoke old credentials
curl -X POST "{{host}}/client/api/api-keys/OLD_ID/revoke-api-key" \
  -H "Cookie: session=your-portal-session"

Signing Secret Rotation

The signing secret can be rotated independently of the API key and secret. This is useful when you want to rotate the HMAC signing material without disrupting basic authentication.

# Rotate signing secret only (Client Portal session auth)
curl -X POST "{{host}}/client/api/api-keys/1/rotate-signing-secret" \
  -H "Cookie: session=your-portal-session"

Response (new secret shown once):

{
  "success": true,
  "data": {
    "signing_secret": "whsec_new_secret_value_here"
  }
}

Rotation steps:

1. Call /rotate-signing-secret -- generates new secret
2. Update your application with the new signing secret
3. Both your HMAC request signing and webhook signature verification update automatically
4. The old signing secret stops working immediately -- plan for a brief transition window

Network Security

HTTPS Only

All API communication must use HTTPS (TLS 1.2+). Plain HTTP requests are rejected. Webhook endpoints must also use HTTPS.

IP Whitelisting

Contact your admin to configure IP whitelisting for your API credential. When enabled, requests from non-whitelisted IPs are rejected with 403 Forbidden, even with valid credentials.

Rate Limiting

The API enforces rate limits per credential:

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header.

Request Timeouts

Set reasonable timeouts in your HTTP client:

Monitoring and Alerting

What to Monitor

Audit Trail

The Starship admin panel logs all credential operations:

• API key generation / revocation
• Signing secret rotation
• HMAC enable / disable
• IP whitelist changes

Contact your admin to review audit logs if you suspect unauthorized credential use.

Security Checklist

Related

• Authentication Overview -- API key setup and migration path
• HMAC Request Signing -- Full signing specification
• Webhooks -- Webhook signature verification