Remote config

Boolean and multivariate flags are helpful for dynamic values that differ from user to user, but sometimes you need a simple way to pass configuration related to your application without having to make code changes or redeploy your app.

Remote config flags enable you to configure a simple flag that always returns the same payload wherever it is called. Remote config flags can also be stored as encrypted values and decrypted on the server side when requested. Encryption/decryption is handled automatically.

You can think of remote config flags as multivariate flags with a single variant which is served for all flag requests. By default, enabled remote config flags roll out to 100% of all users.

Using remote config in client-side apps

Non-encrypted remote config flags are served through the /flags endpoint like any other feature flag, using your project token, which is safe to expose publicly. Read the payload with your SDK's flag payload function. For example, in posthog-js:

const config = posthog.getFeatureFlagPayload('landing-page-config')

This also works for CLIs, scripts, or anything else that can call /flags with your project token.

Note: Flags with encrypted payloads are excluded from /flags entirely, so they can't be read client-side and require a server.

Using remote config on the server

Server-side SDKs fetch remote config payloads using your secret API key. This key is only required for local evaluation and server-side remote config – not for remote config in general. It returns encrypted payloads redacted, so use a personal API key if you need them decrypted. Unlike your project token, it must never be exposed publicly.

There are 3 steps to use remote config flags on the server:

Step 1: Get a secret API key

Initialize the SDK with your public project token. Server-side SDKs also need a secret API key for local evaluation and server-side remote config. This can be a project secret API key (recommended) or the legacy feature flags secure API key. Keep it secret: don't use it in frontend code or expose it to users.

We recommend using a project secret API key with the feature_flag:read scope. Project secret API keys are hashed at rest, scoped to only what they need, and you can create up to 50 per project, so you can issue and roll keys per deployment without affecting the others.

A personal API key is a private credential tied to your account for management API access. Source-map uploads use separate CLI authentication, not the feature_flag:read project secret.

Building a frontend, mobile, or CLI app? Local evaluation and the secret API key are for server-side use only. To evaluate flags from client-side code, use a client-side SDK or call the public /flags endpoint with your project token instead. The project token is safe to expose to users. Never include secret or personal API keys in distributed client code.

Note: Existing feature flags secure API keys (deprecated) and personal API keys continue to work. We recommend switching to a project secret API key. If you use encrypted payloads, keep a personal API key for those requests, since it's the only key that returns them decrypted.

How to create a project secret API key

1. Go to Project secret API keys in your project settings. You need project admin access to create a key.

2. Create a new key with the Local feature flag evaluation preset (the feature_flag:read scope) and give it a label.

3. Copy the key. It's only displayed once, so store it somewhere safe, like a secrets manager.

4. Pass it in the client's options, separately from the public project token. Use secretKey in posthog-node 5.40.0+ or secret_key in synchronous posthog 7.22.1+. Older versions use personalApiKey or personal_api_key, respectively. These legacy options remain deprecated aliases in newer versions. The Java SDK uses personalApiKey. The option name does not change the key's permissions.

Step 2: Initialize PostHog with your secret API key in options

import { PostHog } from "posthog-node"

const client = new PostHog(
    "<ph_project_token>",
    {
        host: "https://us.i.posthog.com",
        // Requires posthog-node 5.40.0+. Older versions use personalApiKey instead.
        secretKey: "<ph_personal_api_key>", // or your project secret API key
        featureFlagsPollingInterval: 30000 // Optional. Measured in milliseconds. Defaults to 30000 (30 seconds)
    }
)

posthog = PostHog::Client.new({
  api_key: "<ph_project_token>",
  host: "https://us.i.posthog.com",
  personal_api_key: 'your secret API key from step 1',
  feature_flags_polling_interval: 30 # Optional. Measured in seconds. Defaults to 30.
})

package main

import (
    "os"
    "time"
    "github.com/posthog/posthog-go"
)

func main() {
    client, _ := posthog.NewWithConfig(
        os.Getenv("POSTHOG_API_KEY"),
        posthog.Config{
            Endpoint:       "https://us.i.posthog.com",
            PersonalApiKey: "your secret API key", // Optional, but much more performant. If this token is not supplied, then fetching feature flag values will be slower.
            DefaultFeatureFlagsPollingInterval: time.Minute * 5, // time.Duration // Optional. Defaults to 5 minutes.
            // NextFeatureFlagsPollingTick: func() time.Duration {} // Optional. Use this to sync polling intervals between instances. For an example see: https://github.com/PostHog/posthog-go/pull/36#issuecomment-1991734125
        },
    )
    defer client.Close()
    // run commands
}

PostHog::init(
    '<ph_project_token>',
    ['host' => 'https://us.i.posthog.com'],
    personalAPIKey: 'your secret API key from step 1'
);
// NOTE: PHP currently doesn't support a poller, so you'll need to reload flags as and when needed, or re-initialize the posthog client

from posthog import Posthog

posthog = Posthog("<ph_project_token>",
    host="https://us.i.posthog.com",
    poll_interval=30, # Optional. Measured in seconds. Defaults to 30.
    # Requires posthog 7.22.1+. Older versions use personal_api_key instead.
    secret_key="<ph_personal_api_key>" # or your project secret API key
)

// Note: We don't recommend passing these in directly.
// Instead, rely on the config system and set the personal 
// api key in a secrets manager.
var client = new PostHogClient(
    new PostHogOptions {
        ProjectToken = "<ph_project_token>",
        PersonalApiKey = "your secret API key from step 1"
    });

import com.posthog.server.PostHog;
import com.posthog.server.PostHogConfig;
import com.posthog.server.PostHogInterface;

PostHogConfig config = PostHogConfig.builder("<ph_project_token>")
    .host("https://us.i.posthog.com")
    .personalApiKey("your secret API key from step 1")
    .pollIntervalSeconds(30)  // Optional. Measured in seconds. Defaults to 30.
    .build();

PostHogInterface posthog = PostHog.with(config);

use posthog_rs::ClientOptionsBuilder;

let options = ClientOptionsBuilder::default()
    .api_key("<ph_project_token>")
    .personal_api_key("your secret API key from step 1")
    .enable_local_evaluation(true)
    .poll_interval_seconds(30) // Optional. Measured in seconds. Defaults to 30.
    .build()
    .unwrap();

let client = posthog_rs::client(options).await;

config :posthog,
  api_host: "https://us.i.posthog.com",
  api_key: "<ph_project_token>",
  secret_key: System.fetch_env!("POSTHOG_FEATURE_FLAGS_SECURE_API_KEY"),
  feature_flags_poll_interval_ms: 30_000

Note: By default, initializing PostHog with your secret API key enables local evaluation, but this can be disabled in posthog-node by setting enableLocalEvaluation: false in your config.

Step 3: Use remote config flags

const config = await client.getRemoteConfigPayload("landing-page-config")
// config is a JsonType

config = posthog.get_remote_config_payload('landing-page-config')
# config is a JSON encoded string. It will need to be parsed as a JSON object.

config, err := client.GetRemoteConfigPayload("landing-page-config")
// config is a JSON encoded string. It will need to be parsed as a JSON object.

config = posthog.get_remote_config_payload('landing-page-config')
# config is returned as a parsed object.

var config = await posthog.GetRemoteConfigPayloadAsync("landing-page-config");
// config is a JsonDocument

Note: Remote config flags are meant to always serve payloads and be called with the flag payload function in each SDK. If getFeatureFlag is called instead, the SDK simply returns true

Encrypted payloads

Encrypted payloads are only available server-side, through the authenticated remote config API. Authenticate with a personal API key to receive the decrypted payload – secret API keys, including project secret API keys, return encrypted payloads redacted.

Related

• Feature flags vs configuration: Which should you choose?