Choose and set up an SDK
Decide whether your code runs in a browser or on a server, create the matching key and read a flag with a first working check.
- Time
- About 8 min
- Who can do it
- Admin to create the key. Anyone can add the SDK to their app.
- Where
- API Keys in the console, then your own code
- You finish with
- An app that reads a flag with the right kind of key and survives an outage
What and why#
What an SDK does#
An SDK is a small library that fetches your flags, keeps them fresh and answers isEnabled or getValue in your code. You can call the HTTP API directly, but an SDK adds caching, retries, an offline fallback and, on servers, local evaluation with the same engine the server uses.
Client or server#
The one decision is where your code runs. Code a visitor can inspect, such as a browser or a mobile app, gets a client key: it can only ask “what is on for this person?” and never sees your targeting. Code you control, such as a backend, gets a server key: it downloads the full configuration and evaluates locally, which is faster and keeps per-person data on your side.
Before you start#
- A project with a flag turned on in an environment. See Flags.
- Your server address. Every SDK needs it as
baseUrl, and there is no default host. - An Admin to create the key. Creating a key needs the
api_keys.createpermission, and a key can never do more than its creator.
Pick client or server#
| Runs in | Key | Description |
|---|---|---|
| Browser, mobile app | client key | Returns only enabled, variant and value for one person. Safe to ship. Used by React, React Native and the Next.js client provider. |
| Backend service | server key | Downloads configuration and evaluates it locally. Keep it in a private environment variable. Used by Node.js, NestJS, Go, Python, PHP, Laravel, .NET and Next.js on the server. |
Walk through it#
Create the key
In API Keys, choose New API Key. In Create API Key, fill in:
Create API Key fields Field Type Description Name required Up to 80 characters, such as Checkout service (prod). It appears in the audit log when the key acts. Type required Client, Server or Admin. Choose Client for browsers and mobile apps, Server for your backend. Admin is for automation, never for an SDK in an app. Project required The project whose flags the key reads. Environment optional All environments, or one. Limit a production key to production only. A key that covers every environment needs the environment option in the SDK. Expires optional Never, 30 days, 90 days or 1 year. A key that expires limits the damage if one leaks. The Create API Key dialog for a backend key limited to Production. Create Key stays off until the name and project are filled in. The only time the whole key is shown. Closing the dialog discards it. You should see. The key is shown once in the dialog and then listed with its type, project and environment. Keys start withfs_client_,fs_srv_orfs_admin_.Install and connect
Pick your platform. Create the client once and reuse it.
tsx // npm install @flagswift/react import { FlagClient, FlagProvider, useFlag } from "@flagswift/react"; const client = new FlagClient({ apiKey: process.env.NEXT_PUBLIC_FLAGSWIFT_KEY!, // fs_client_... baseUrl: "https://flags.example.com", environment: "production", // only for project-wide keys }); export const App = () => ( <FlagProvider client={client} user={{ identifier: "user-123" }}> <Dashboard /> </FlagProvider> ); const Dashboard = () => (useFlag("new-dashboard") ? <NewDashboard /> : <OldDashboard />);Pass who the person is
A flag decides per person. Pass
identifierfor the user,accountfor their organization anddevicefor the install. If a flag buckets by user and you pass none, it serves the off result with the reasonNO_IDENTIFIER.Set a fallback
A flag check never throws. Before the first response an SDK returns your fallback, then
false. If a refresh fails, the last good flags keep serving.Check the key with one request
Before wiring code, confirm the key and environment with the HTTP API. The SDK makes the same calls.
Do it with the API
The Evaluation API authenticates with the key as a bearer token and uses no cookies. Leave out
envfor a key limited to one environment. The server call also acceptsuser_identifierwith the defaultmode=evaluate, andexplain=trueadds each result's reason.Request # Client key: the result for one person curl -s "https://flags.example.com/api/v1/evaluation/client?user_identifier=user-123&env=production" \ -H "Authorization: Bearer $FLAGSWIFT_CLIENT_KEY" # Server key: the full configuration, for local evaluation curl -s "https://flags.example.com/api/v1/evaluation/server?mode=config&env=production" \ -H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY"Client response { "environment": "production", "hashVersion": 1, "version": "f1c2", "flags": { "new-dashboard": { "enabled": true, "version": 7 }, "checkout-layout": { "enabled": true, "variant": "compact", "value": "compact", "version": 3 } } }
Not every SDK is proven
What to check#
- The flag returns the value you set in the console for that environment.
- Turn the flag off and see the app follow within the refresh interval. The default is 30 seconds.
- Stop the server briefly and confirm the app keeps working with the last flags or your fallback.
- No server or admin key appears in a browser bundle or in source control.
Good to know#
Create the client once
| Option | Description |
|---|---|
| baseUrl | Required. There is no default host. |
| environment | Needed only for a key that covers every environment. |
| refreshInterval | Milliseconds between checks. Default 30000; 0 turns polling off. |
| streaming | Refresh the moment a flag changes. Default false, and it falls back to polling by itself. |
| fallbacks | Values served until flags load, for an unknown flag, or when the server cannot be reached. |
Can I put a server key in my web app?
Why does my flag return false before data arrives?
false. Await the SDK's ready or initialize call, or provide a fallback for every flag you read.How quickly does a change reach my app?
Which environment do I get if I leave it out?
If something goes wrong#
401 with AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY
Why: The Authorization header is missing, or the key is unknown, revoked or expired.
Fix: Send Authorization: Bearer KEY. Check the key on the API Keys page and create a new one if needed.
403 with AUTH_ENVIRONMENT_MISMATCH
Why: The key is limited to one environment and the request asked for another.
Fix: Drop the environment option, or use a key for that environment.
400 with ENV_REQUIRED
Why: A key that covers every environment sent no environment.
Fix: Set environment in the SDK, or add ?env=production to the request.
403 with AUTH_INSUFFICIENT_SCOPE
Why: A client key called a server endpoint, or the key lacks the scope the endpoint needs.
Fix: Use a server key for configuration, or a client key for evaluation.
Every flag returns false and the reason is NO_IDENTIFIER
Why: The flag buckets by user, account or device and you passed none of them.
Fix: Pass identifier, account or device as the flag's rollout expects.
429 with RATE_LIMITED
Why: The key made more requests than its allowance, which defaults to 600 a minute.
Fix: Wait for the Retry-After seconds, and reuse one client instead of creating one per request.