Skip to content
FlagSwiftDocs

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.create permission, and a key can never do more than its creator.

Pick client or server#

Where your code runs decides the key
Runs inKeyDescription
Browser, mobile appclient keyReturns only enabled, variant and value for one person. Safe to ship. Used by React, React Native and the Next.js client provider.
Backend serviceserver keyDownloads 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#

  1. Create the key

    In API Keys, choose New API Key. In Create API Key, fill in:

    Create API Key fields
    FieldTypeDescription
    NamerequiredUp to 80 characters, such as Checkout service (prod). It appears in the audit log when the key acts.
    TyperequiredClient, 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.
    ProjectrequiredThe project whose flags the key reads.
    EnvironmentoptionalAll environments, or one. Limit a production key to production only. A key that covers every environment needs the environment option in the SDK.
    ExpiresoptionalNever, 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 with fs_client_, fs_srv_ or fs_admin_.
  2. 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 />);
  3. Pass who the person is

    A flag decides per person. Pass identifier for the user, account for their organization and device for the install. If a flag buckets by user and you pass none, it serves the off result with the reason NO_IDENTIFIER.

  4. 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.

  5. 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 env for a key limited to one environment. The server call also accepts user_identifier with the default mode=evaluate, and explain=true adds 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

The JavaScript, Go, Python and PHP SDKs have been tested against shared evaluation vectors. The .NET SDK has not been compiled or run, Java was tested with javac and JUnit but not a Maven build, and Laravel only against stand-ins. Package names and coordinates shown for these may be placeholders. Smoke-test against your own server first.

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

Create one client at startup and share it. A server SDK keeps a copy of the configuration in memory, so creating it per request re-downloads everything and defeats local evaluation.
Options you will use most
OptionDescription
baseUrlRequired. There is no default host.
environmentNeeded only for a key that covers every environment.
refreshIntervalMilliseconds between checks. Default 30000; 0 turns polling off.
streamingRefresh the moment a flag changes. Default false, and it falls back to polling by itself.
fallbacksValues 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?
No. A server key reads full flag configuration, including targeting lists. Only a client key is safe to ship in a browser or mobile app.
Why does my flag return false before data arrives?
Before the first response an SDK returns your fallback, then 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?
Within the refresh interval (30 seconds by default), or immediately with streaming turned on. A key can be rate limited at 600 requests a minute by default.
Which environment do I get if I leave it out?
For a key limited to one environment, that one. A key that covers every environment must name one: there is no silent default to production.

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.