Authentication

Secure your API requests with API keys

The FluxCascade API uses API keys for authentication. Every request to the API must include a valid API key. API keys are tied to your user account and can be scoped with different permission levels.

Creating API Keys

Navigate to Settings → API Keys
Click "Create API Key"
Enter a descriptive name (e.g., "Production Sync", "Development Testing")
Select the appropriate scope (read, write, or admin)
Copy your API key immediately - it won't be shown again!

Keep your API keys secure

Never commit API keys to version control, share them in public channels, or expose them in client-side code. Treat them like passwords.

Using API Keys

Include your API key in every request using one of these methods:

Authorization Header (Recommended)

Use the standard Bearer token format in the Authorization header.

curl -X GET "https://api.fluxcascade.io/api/v1/connections" \
  -H "Authorization: Bearer YOUR_API_KEY"

X-API-Key Header

Alternatively, use a custom X-API-Key header.

curl -X GET "https://api.fluxcascade.io/api/v1/connections" \
  -H "X-API-Key: YOUR_API_KEY"

API Scopes

API keys are assigned a scope that determines what actions they can perform. Follow the principle of least privilege - only grant the minimum scope needed.

Scope	Permissions	Use Case
read	List and view connections List and view mappings List and view sync history	Dashboards, monitoring, reporting
write	Everything in read scope Create and update mappings Trigger sync jobs	Automation, integrations, scheduled tasks
admin	Everything in write scope Delete mappings and connections Manage API keys	Administrative tools, full access needs

Rate Limiting

The API enforces rate limits to ensure fair usage and platform stability.

100

Requests per minute

Per API Key

Each key has its own limit

429

Status when exceeded

Rate Limit Headers

Every response includes headers to help you track your usage:

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

Authentication Errors

When authentication fails, you'll receive one of these error responses:

401Unauthorized

Missing or invalid API key

{
  "error": "authentication_failed",
  "message": "Invalid or missing API key"
}

403Forbidden

API key doesn't have required scope

{
  "error": "insufficient_scope",
  "message": "This endpoint requires 'write' scope"
}

429Too Many Requests

Rate limit exceeded

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 45 seconds."
}