Configuration | Sylphx Documentation

Get Your API Keys

Create a Project

Go to the Sylphx Console and create a new project.

Copy Your Keys

Navigate to Project → API Keys. You'll find two keys per environment:

Property	Type	Description
`Secret Key`	`sk_{env}_{ref}_{64hex}`	Server-side only — full SDK access. Never expose to the browser.
`Publishable Key`	`pk_{env}_{ref}_{32hex}`	Client-safe — read-only access (feature flags, analytics, public config).

Self-describing keys (ADR-021)

Your project ref is embedded in both keys — no separate App ID variable needed. The SDK automatically routes requests to the correct project. Legacy app_* keys continue to work.

Add to Your Environment

Add both keys to your environment file.

Environment Variables

.env.local

# Server-side only — never expose to the browser
SYLPHX_SECRET_KEY=sk_dev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Client-safe publishable key
NEXT_PUBLIC_SYLPHX_KEY=pk_dev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security

SYLPHX_SECRET_KEY must only be used in server-side code: API routes, Server Components, and middleware. It grants full access to your project's BaaS services.

That's All You Need

No platform URL, no App ID, no project slug. The SDK derives everything from your key. Get keys from Console → Project → API Keys.

Root Layout (Next.js App Router)

Fetch server-side config once in your root layout and pass it to SylphxProvider. This pre-fetches plans, feature flags, consent types, and OAuth providers in one call:

app/layout.tsx

import { getAppConfig } from '@sylphx/sdk/server'
import { SylphxProvider } from '@sylphx/sdk/react'

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const config = await getAppConfig({
    secretKey: process.env.SYLPHX_SECRET_KEY!,
    appId: process.env.NEXT_PUBLIC_SYLPHX_KEY!,  // publishable key
  })

  return (
    <html lang="en">
      <body>
        <SylphxProvider
          appId={process.env.NEXT_PUBLIC_SYLPHX_KEY!}
          config={config}
        >
          {children}
        </SylphxProvider>
      </body>
    </html>
  )
}

Server-Side API Client

For server-side API calls (API routes, Server Actions, background jobs):

lib/sylphx.ts

import { createConfig } from '@sylphx/sdk'

// Create once, reuse everywhere
export const config = createConfig({
  secretKey: process.env.SYLPHX_SECRET_KEY!,
})

// For REST API access (OpenAPI client)
import { createServerClient } from '@sylphx/sdk/server'

export const client = createServerClient({
  secretKey: process.env.SYLPHX_SECRET_KEY!,
})

Middleware

Add auth routing and session management — no manual /api/auth/* routes needed:

middleware.ts

import { createSylphxMiddleware } from '@sylphx/sdk/nextjs'

export default createSylphxMiddleware({
  publicRoutes: ['/', '/about', '/pricing', '/login', '/signup'],
})

export const config = {
  matcher: ['/((?!_next|.*\\..*).*)', '/'],
}

Key Format Reference

Keys encode environment and project ref — the SDK reads both automatically:

Property	Type	Description
`sk_dev_* / pk_dev_*`	`Development`	Local dev and testing. Relaxed rate limits.
`sk_stg_* / pk_stg_*`	`Staging`	Pre-production. Production-like settings.
`sk_prod_* / pk_prod_*`	`Production`	Live production. Strict rate limits.
`sk_prev_* / pk_prev_*`	`Preview`	Ephemeral preview environments.

Auto-Detection

The SDK detects environment from the key prefix and routes to the correct backend automatically. Use different keys per environment — never share keys across environments.

Content Security Policy (CSP)

If your app uses a CSP, allow connections to Sylphx domains:

Required CSP

connect-src 'self' https://sylphx.com https://*.sylphx.com;

next.config.ts

const nextConfig = {
  async headers() {
    return [{
      source: '/:path*',
      headers: [{
        key: 'Content-Security-Policy',
        value: [
          "default-src 'self'",
          "connect-src 'self' https://sylphx.com https://*.sylphx.com",
        ].join('; '),
      }],
    }]
  },
}

Authentication

Set up auth for your app

Billing

Add subscriptions and payments