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}_{64hex}`	Server-side only — full SDK access. Never expose to the browser.
`Publishable Key`	`pk_{env}_{32hex}`	Client-safe — read-only access (feature flags, analytics, public config).

Pure entropy keys (ADR-055)

Keys are pure entropy — no embedded routing or project ref. Use a Connection URL (sylphx://[email protected]) for the simplest setup: one env var, zero ambiguity.

Add to Your Environment

Add both keys to your environment file.

Environment Variables

.env.local

# Server connection URL — never expose to the browser
SYLPHX_URL=sylphx://sk_dev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@bold-river-a1b2c3.sylphx.com

# Client connection URL — safe to embed in the browser bundle
NEXT_PUBLIC_SYLPHX_URL=sylphx://pk_dev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@bold-river-a1b2c3.sylphx.com

Security

SYLPHX_URL contains an sk_* credential and 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

One env var per credential type. Each connection URL bundles the credential and the project slug — no separate SYLPHX_PROJECT_REF needed. Get the URLs 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(process.env.SYLPHX_URL!)

  return (
    <html lang="en">
      <body>
        <SylphxProvider
          connectionUrl={process.env.NEXT_PUBLIC_SYLPHX_URL!}
          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 { createClient } from '@sylphx/sdk'

// Create once, reuse everywhere — one env var, parsed as a URI
export const sylphx = createClient(process.env.SYLPHX_URL!)

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

export const client = createServerClient(process.env.SYLPHX_URL!)

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 only their type and target environment — pure entropy with no embedded routing. The connection URL host carries the project slug:

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