Authentication

Sparkient supports two authentication methods. Use whichever fits your use case.

API Keys (Recommended for Production)

API keys are the primary way to authenticate programmatic access. They are scoped to your organization and include built-in rate limiting.

Getting a Key

1. Sign in to the Sparkient Dashboard
2. Navigate to Settings → API Keys
3. Click Create API Key and copy the generated key

Using a Key

Pass your API key as a Bearer token in the Authorization header:

curl -X POST https://api.sparkient.ai/api/v1/decide \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "decision_type": "my_type", "input": { "text": "hello" } }'

Key Format

API keys follow the format sk_live_ followed by a random string. They are:

• Hashed at rest — stored as HMAC-SHA256 hashes with per-key salts. The raw key is never stored.
• Rate-limited — each key has a configurable rate limit (default: 600 requests/minute).
• Organization-scoped — all resources accessed through a key are filtered to your organization.

Key Rotation

To rotate a key:

1. Create a new API key in the dashboard
2. Update your application to use the new key
3. Revoke the old key

Firebase JWT (Dashboard & Frontend)

The Sparkient Dashboard uses Firebase Authentication for user sessions. This is primarily for the dashboard UI and is not recommended for server-to-server integration.

How It Works

1. Users sign in via email/password, Google OAuth, or GitHub OAuth
2. Firebase issues a JWT (ID token)
3. The dashboard sends this token as Authorization: Bearer <idToken>
4. The API verifies the token with Firebase Admin SDK
5. On first login, a user record is auto-provisioned and linked to an organization

When to Use

Error Responses

All error responses follow a consistent envelope format:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key"
  }
}

Rate Limit Headers

API key requests include rate limit headers on every response:

Security Best Practices

• Never expose API keys in client-side code. Use them only in server-side applications.
• Use environment variables to store keys — never commit them to source control.
• Rotate keys regularly and revoke any keys that may have been compromised.
• Use separate keys for development and production environments.