Authentication

Supascale API supports two authentication methods: session-based for web UI and API key-based for programmatic access.

Authentication Methods

Session Authentication

Used automatically by the web interface.

How It Works

1. User logs in via /api/auth/signin
2. Server sets session cookie
3. Subsequent requests include cookie automatically
4. Sessions managed by NextAuth.js

Session Endpoints

POST /api/auth/signin     # Sign in
POST /api/auth/signout    # Sign out
GET  /api/auth/session    # Get current session

API Key Authentication

For programmatic access from scripts, CI/CD, or integrations.

Request Format

Include the API key in the X-API-Key header:

curl https://supascale.example.com/api/v1/projects \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

API Key Format

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefix: sk_live_
• 32 alphanumeric characters

Creating API Keys

See API Keys for detailed instructions.

curl -X POST https://supascale.example.com/api/v1/settings/api-keys \
  -H "X-API-Key: admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "permissions": {
      "projects": "write",
      "backups": "read",
      "tasks": "none",
      "cloudStorage": "none",
      "system": "none"
    }
  }'

Permissions

API keys have granular permissions per resource:

Resources

Permission Check

When a request is made:

1. Extract API key from header
2. Validate key exists and not expired
3. Determine required permission for endpoint
4. Compare against key's permissions
5. Allow or deny with 403

Error Responses

401 Unauthorized

No or invalid authentication:

{
  "success": false,
  "error": "Unauthorized"
}

Causes:

• Missing X-API-Key header
• Invalid API key
• Expired API key

403 Forbidden

Authenticated but insufficient permissions:

{
  "success": false,
  "error": "Insufficient permissions"
}

Causes:

• API key lacks required permission
• Attempting write operation with read-only key

Rate Limiting

API requests are rate limited to prevent abuse:

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642089600

When exceeded:

{
  "success": false,
  "error": "Rate limit exceeded"
}

Status: 429 Too Many Requests

Best Practices

Security

1. Use HTTPS only - Never send keys over HTTP
2. Rotate keys regularly - Every 90 days recommended
3. Minimum permissions - Only grant what's needed
4. Set expirations - Limit key lifetime

Implementation

1. Store securely - Use environment variables or secrets manager
2. Never commit - Keep keys out of version control
3. Handle errors - Check for 401/403 responses
4. Implement retry - Handle rate limits gracefully

Example: Environment Variable

# .env
SUPASCALE_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Usage
curl https://supascale.example.com/api/v1/projects \
  -H "X-API-Key: $SUPASCALE_API_KEY"

Example: Error Handling (Node.js)

async function callApi(endpoint) {
  const response = await fetch(`https://supascale.example.com${endpoint}`, {
    headers: {
      'X-API-Key': process.env.SUPASCALE_API_KEY
    }
  });

  if (response.status === 401) {
    throw new Error('Invalid or expired API key');
  }

  if (response.status === 403) {
    throw new Error('Insufficient permissions');
  }

  if (response.status === 429) {
    // Wait and retry
    await sleep(60000);
    return callApi(endpoint);
  }

  return response.json();
}

Testing Authentication

Verify API Key

# Should return project list if key is valid
curl https://supascale.example.com/api/v1/projects \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Check Permissions

# Returns 403 if key lacks projects:write permission
curl -X POST https://supascale.example.com/api/v1/projects \
  -H "X-API-Key: read-only-key" \
  -H "Content-Type: application/json" \
  -d '{"id": "test"}'