Configuration and auth

Production evaluation uses the remote adapter. It speaks POST /v1/flags/evaluate and POST /v1/targets/register. POST /v1/capture remains on the wire. All seven remotes implement register. Auth on the wire is Authorization: Bearer <key>. Server keys use project-api-key_…. Browser keys use fw_public_…. Never send PostHog phc_ / phs_ / phx_ keys on this path.

The SDK reads no environment variables. FW_API_URL and FW_PROJECT_API_KEY are not auto-read. Your application may read them and pass them in as apiUrl / apiKey. FW_DEPRECATION_WARNINGS no longer exists. The flags alias is silent at runtime in every language except Python, which emits one DeprecationWarning per process on first access.

`mode` is required

initFireweave({ mode: 'remote', apiKey, apiUrl })
initFireweave({ mode: 'local',  local: { controlPoints: { … } } })

mode is 'remote' or 'local'. The SDK never infers it. Remote without credentials is a boot error. Local with credentials supplied is also a boot error. With inference, a mistyped production credential silently became local evaluation. Every control point served its default, nothing raised, and the boot log stayed green. The symptom was a feature that never ramped — indistinguishable from a rollout nobody started. Requiring mode makes that state unreachable by accident.

	`local`	`remote`
Adapter	Local, seeded map	Remote, `POST /v1/flags/evaluate`
Network	None	fw-server
Required options	`local.controlPoints` (may be empty)	`apiKey`, `apiUrl`
Unknown key	`default`, `reason: DEFAULT`	`default`, `reason: ERROR`, `FlagNotFound`
`registerTarget`	Recorded in-process + traced	`POST /v1/targets/register`

Init validation (fails loudly, kind Configuration):

Condition	Result
`mode` absent or unrecognised	`Configuration`
`mode: 'remote'`, `apiKey` or `apiUrl` missing/blank	`Configuration`
`apiUrl` fails the host allowlist	`Configuration`
`mode: 'local'` with credentials supplied	`Configuration`

Per-language setup

import { initFireweave } from '@fireweaveai/server-sdk';

const fireweave = await initFireweave({
  mode: 'remote',
  apiUrl: process.env.FW_API_URL!,
  apiKey: process.env.FW_PROJECT_API_KEY!,
});

Package: @fireweaveai/server-sdk. Runs on Node ≥ 20.20, Bun ≥ 1.2, Deno ≥ 2.0. Deno needs no install step: import { initFireweave } from 'npm:@fireweaveai/server-sdk'. You still need --allow-net to reach fw-server. You do not need --allow-env unless your code reads the environment.

Constructor fields are required. The package never reads process, Deno, or import.meta.env.

import { initFireweave } from '@fireweaveai/web-sdk';

const fireweave = await initFireweave({
  mode: 'remote',
  apiKey: PUBLIC_FW_PROJECT_API_KEY, // fw_public_…
  apiUrl: PUBLIC_FW_API_URL,
  context: { targetingKey: 'anonymous' },
});

Vendor key shapes phc_ / phs_ / phx_ are rejected at construction (Configuration).

from fireweave import init_fireweave

client = init_fireweave(
    mode="remote",
    api_key="project-api-key_...",
    api_url="https://app-server.fireweave.ai",
)

client, err := fireweave.Init(fireweave.Options{
    Mode:   fireweave.ModeRemote,
    APIKey: os.Getenv("FW_PROJECT_API_KEY"),
    APIURL: os.Getenv("FW_API_URL"),
})

Module: github.com/FireWeave-HQ/fireweave-sdk/sdks/go/v2. os.Getenv is your code, not the SDK.

FireweaveClient client = Fireweave.init(InitOptions.remote(
    System.getenv("FW_PROJECT_API_KEY"),
    System.getenv("FW_API_URL")));

Fireweave.init reads no environment. System.getenv is your code. Artifacts are ai.fireweave:fireweave-sdk (0.1.0-SNAPSHOT, not on Maven Central yet).

let client = init_fireweave(InitOptions::remote(
    "project-api-key_...",
    "https://app-server.fireweave.ai",
)).unwrap();

Crate: fireweave.

let client = try await initFireweave(.remote(InitFireweaveRemoteOptions(
    apiKey: apiKey,
    apiUrl: apiUrl
)))

Package: Fireweave. Zero SPM dependencies.

Browser keys

A browser key is public by construction — anything in a bundle is readable. Use the scoped fw_public_… family. That family is scoped to flags:evaluate + events:write. It is the supported way to authenticate @fireweaveai/web-sdk against the public control-point routes:

POST /v1/flags/evaluate
POST /v1/capture
POST /v1/targets/register

A fw_public_ key never falls through to the attest verifier. The attest plane rejects the family outright. Do not put an attest:write project key (project-api-key_… used for deploy attestation) in a browser bundle. fw-server rate-limits per key. Routes answer 429 with Retry-After when a key exceeds its limit. Where the app has a same-origin backend, injecting the key server-side (a BFF) remains the better pattern and avoids publishing a credential at all. The remote protocol also accepts x-api-key. Shipped adapters document and send Bearer.

HTTPS and host allowlists

https is required off-loopback. Plain http is allowed on loopback only (localhost, 127.0.0.1, ::1) for the test stub.

Surface	Default allowlist
Node, Web, Python, Go, Rust, Swift	`app-server.fireweave.ai`, `staging-app-server.fireweave.ai`, plus loopback
Java	Those Fireweave hosts and five leftover PostHog hostnames, plus loopback. Not a live vendor integration

Go’s default is deliberately not derived from the configured APIURL hostname. That would make the default permissive by construction. A self-hosted fw-server must list its own host, or pass AllowedHosts: []string{"*"} to opt out. A host that fails the allowlist or scheme check is Configuration. Error messages do not echo the host or the key. Use the fw-server base URL you were given. The hostnames above are the SDK allowlist, not a promise that they are your project’s endpoint.

Credentials

Pass the key as an init option. Store it in your secret manager. Do not commit it.
Error messages and logs redact keys, bearer tokens, and FW_PROJECT_API_KEY values.
Server: project-api-key_…. Browser: fw_public_….

Timeouts

Setting	Default
Evaluate / register request timeout	3000 ms on remote adapters that expose it
Shutdown / close deadline	10000 ms
Web prefetch ceiling (STALE)	5000 ms (`DEFAULT_FLAGS_READY_TIMEOUT_MS`)

initFireweave on Node does not expose requestTimeoutMs directly. Use lower-level construction (FireweaveRemoteAdapter + FireweaveRuntime) if you need it.

Reliability

Evaluate is a remote round trip on the server SDKs. Web prefetches one batch /v1/flags/evaluate per context.
Retries: registerTarget retries once when the kind is retryable. Evaluate is not retried by the remote adapter.
v1 reads are side-effect free. No evaluate emits capture as a consequence of being called.

What this page does not claim

The SDK auto-reading FW_* from the environment.
FW_DEPRECATION_WARNINGS.
Automatic retries on evaluate.
Container or serverless runtimes as a supported class.

Initialize, ready, shutdown

Required mode, STALE, and fail-open

Errors

What a default-valued decision means

Get Started

SDKs

Concepts

Production

CLI

Terraform

Testing

Troubleshooting

Migration

Reference

Configuration and auth

`mode` is required

Per-language setup

Browser keys

HTTPS and host allowlists

Credentials

Timeouts

Reliability

What this page does not claim

Next

Initialize, ready, shutdown

Errors

​mode is required

​Per-language setup

​Browser keys

​HTTPS and host allowlists

​Credentials

​Timeouts

​Reliability

​What this page does not claim

​Next

Initialize, ready, shutdown

Errors

`mode` is required

Per-language setup

Browser keys

HTTPS and host allowlists

Credentials

Timeouts

Reliability

What this page does not claim

Next