API Keys & Security

Securely authenticate your application's requests to StackForDevs APIs with public and secret keys.

Understanding Key Types

StackForDevs uses two types of API keys to provide flexible security for different use cases:

Public Keys (stk_pub_...)

Public API keys are safe to use in client-side applications:

• Where to use: Browser apps, mobile apps, single-page applications (SPAs)
• What they allow: User-facing operations like login, registration, fetching user data
• Security: Safe to expose in client code, but still should be treated carefully
• Rate limits: Subject to standard rate limits per project

Secret Keys (stk_sec_...)

Secret API keys must be kept confidential and used only server-side:

• Where to use: Backend servers, API proxies, server-side scripts only
• What they allow: Privileged operations like creating users, sending notifications, billing operations
• Security: Must never be exposed in client-side code, committed to version control, or shared
• Capabilities: Full access to all API operations for your project

Generating API Keys

API keys are automatically generated when you create a project:

1. Log in to your StackForDevs Dashboard
2. Navigate to the Projects page
3. Enter a name for your project and click Create Project
4. API keys (public and secret) are automatically generated for your new project

Key Rotation

For security best practices, rotate your API keys periodically:

1. Generate a new set of keys in your dashboard
2. Update your application to use the new keys
3. Verify everything works with the new keys
4. Revoke the old keys in your dashboard

Using API Keys in Requests

Include your API keys in the request headers along with your tenant and project IDs:

Required Headers

x-api-key: YOUR_PUBLIC_KEY
x-secret-key: YOUR_SECRET_KEY
x-tenant-id: YOUR_TENANT_ID
x-project-id: YOUR_PROJECT_ID
Content-Type: application/json

Example Request

curl -X POST https://auth.stackfordevs.com/v1/register \
  -H "Content-Type: application/json" \
  -H "x-api-key: stk_pub_abc123..." \
  -H "x-secret-key: stk_sec_xyz789..." \
  -H "x-tenant-id: tenant-uuid-here" \
  -H "x-project-id: project-uuid-here" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!"
  }'

Client-Side vs Server-Side

For maximum security, use a two-tier architecture:

// ❌ DON'T: Use secret keys in browser
fetch('https://auth.stackfordevs.com/v1/register', {
  headers: {
    'x-secret-key': 'stk_sec_...'  // NEVER do this!
  }
})

// ✅ DO: Call your own API server instead
fetch('http://localhost:3001/api/auth/register', {
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email, password })
})

// Your server then calls StackForDevs with the secret key

Security Best Practices

1. Never Commit Keys to Version Control

# Add to your .gitignore
.env
.env.local
.env.production
config/credentials.json

2. Use Environment Variables

# .env file (never commit this!)
STACKFORDEVS_PUBLIC_KEY=stk_pub_...
STACKFORDEVS_SECRET_KEY=stk_sec_...
STACKFORDEVS_TENANT_ID=...
STACKFORDEVS_PROJECT_ID=...

# Access in your code
const apiKey = process.env.STACKFORDEVS_PUBLIC_KEY;

3. Implement Key Rotation

• Rotate keys every 90 days or after any security incident
• Keep old keys active briefly during rotation to avoid downtime
• Monitor which keys are being used via the dashboard

4. Use the Same Project Across Environments

Use the same project ID and API keys across all your environments (dev, staging, production) for each SaaS product. This prevents configuration drift and ensures consistency.

# Same .env file for dev, staging, and production
STACKFORDEVS_PUBLIC_KEY=stk_pub_...      # Same for all environments
STACKFORDEVS_SECRET_KEY=stk_sec_...      # Same for all environments
STACKFORDEVS_TENANT_ID=...               # Your tenant ID
STACKFORDEVS_PROJECT_ID=...              # Same project for all environments

# Your environment-specific config
NODE_ENV=production
DATABASE_URL=postgres://prod-db

Create separate projects only for different SaaS products, not for different environments of the same product.

5. Monitor API Key Usage

Track your API key usage in the Usage Dashboard:

• View requests per key
• Identify unusual patterns
• Set up alerts for quota limits
• Review which keys are actively being used

Next Steps