Get Your API Keys
1
Create a Project
Go to the Sylphx Console and create a new project.
2
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.3
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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSecurity
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('; '),
}],
}]
},
}