OpenFeature and OFREP

OpenFeature is a vendor-neutral standard API for feature flags. Its Remote Evaluation Protocol (OFREP) defines an HTTP API for flag evaluation. Toggld's evaluation API implements OFREP, so OFREP clients from the OpenFeature project can read Toggld flags.

Toggld ships an SDK for Node.js only. For other languages, use an OFREP provider with the OpenFeature SDK for that language.

What you needCopy Anchor Link

The token selects the workspace and the environment. You do not send the environment in the request. See API keys.

Toggld serves only these two OFREP endpoints.

Find a providerCopy Anchor Link

The OpenFeature ecosystem page lists the available OFREP providers. Filter it by "OFREP". It lists providers for several languages, such as JavaScript, Go, Python, Java, and .NET.

Every provider needs two things from you:

1. The base URL https://api.toggld.io. The provider adds the /ofrep/v1/... paths.
2. The Authorization header with the value Bearer followed by your token. Toggld rejects requests without it with HTTP 401.

Example: JavaScriptCopy Anchor Link

This example uses the OpenFeature project's server-side OFREP provider, @openfeature/ofrep-provider, with the OpenFeature Node.js SDK.

npm install @openfeature/server-sdk @openfeature/ofrep-provider

import { OpenFeature } from "@openfeature/server-sdk";
import { OFREPProvider } from "@openfeature/ofrep-provider";

await OpenFeature.setProviderAndWait(
  new OFREPProvider({
    baseUrl: "https://api.toggld.io",
    headers: { Authorization: `Bearer ${process.env.TOGGLD_SDK_KEY}` },
  }),
);

const client = OpenFeature.getClient();
const enabled = await client.getBooleanValue("new-checkout", false, { targetingKey: "user-123" });

TOGGLD_SDK_KEY=ffk_YOUR_SECRET_KEY

For browsers, the OpenFeature project publishes @openfeature/ofrep-web-provider, which uses the OpenFeature Web SDK. Give it a public token, never a secret key:

import { OpenFeature } from "@openfeature/web-sdk";
import { OFREPWebProvider } from "@openfeature/ofrep-web-provider";

OpenFeature.setProvider(
  new OFREPWebProvider({
    baseUrl: "https://api.toggld.io",
    headers: { Authorization: "Bearer ffp_YOUR_PUBLIC_TOKEN" },
  }),
);

Read the provider documentation for options such as polling and caching. These packages and their options belong to the OpenFeature project and can change.

What Toggld returnsCopy Anchor Link

Toggld's OFREP responses follow the OFREP specification:

• A successful single evaluation returns HTTP 200 with key, value, reason, and, when present, variant and metadata.
• An unknown flag returns HTTP 404 with { "key", "errorCode": "FLAG_NOT_FOUND" }.
• A failed evaluation returns HTTP 400 with { "key", "errorCode", "errorDetails" }. A request body that is not valid JSON gets PARSE_ERROR, and a body with the wrong shape gets INVALID_CONTEXT. For bulk evaluation, these two errors have no key.
• A bulk evaluation returns HTTP 200 with { "flags": [...] }. Each entry is a success or a per-flag failure.

Reasons and error codes use the OpenFeature types. See Errors and the API reference.

The Node.js SDK and OpenFeatureCopy Anchor Link

@toggld/node follows OpenFeature semantics: it returns evaluation details with the standard reasons and error codes, and it never throws on evaluation. It is a standalone client, not a provider for the OpenFeature SDK. To use the OpenFeature Node.js SDK instead, use an OFREP provider as shown above. That provider evaluates remotely. Local evaluation is available only through @toggld/node.