feat: add SecretKey config, deprecate PersonalApiKey (#257)

* feat: add SecretKey config, deprecate PersonalApiKey

Add PostHogOptions.SecretKey, which accepts a Personal API Key or a
Project Secret API Key for local flag evaluation and remote config.
PersonalApiKey becomes a deprecated alias; SecretKey wins when both set.

* chore: address Greptile - SecretKey log message + forward-path config tests

* docs(dotnet): use SecretKey in samples

Author: turnipdabeets

.changeset/secret-key-config.md

@@ -0,0 +1,5 @@
+---
+'PostHog': minor
+---
+
+Add `PostHogOptions.SecretKey` for local feature flag evaluation and remote config. It accepts either a Personal API Key (`phx_...`) or a Project Secret API Key (`phs_...`). The existing `PersonalApiKey` option is now a deprecated alias; when both are set, `SecretKey` takes precedence.

samples/HogTied.Web/Pages/Index.cshtml

@@ -47,17 +47,17 @@
                 </strong>
             </div>
 
-            if (Model.PersonalApiKeyIsSet) {
+            if (Model.SecretKeyIsSet) {
                 <div class="alert alert-info mt-3" role="alert">
                     <strong>
-                        The Personal API Key is set. If it's valid, we'll be using local evaluation.
+                        The Secret Key is set. If it's valid, we'll be using local evaluation.
                     </strong>
                 </div>
             }
             else {
                 <div class="alert alert-info mt-3" role="alert">
                     <strong>
-                        The Personal API Key is NOT set. We'll be using remote evaluation.
+                        The Secret Key is NOT set. We'll be using remote evaluation.
                     </strong>
                 </div>
             }

samples/HogTied.Web/Pages/Index.cshtml.cs

@@ -24,7 +24,7 @@ public class IndexModel(IOptions<PostHogOptions> options, IPostHogClient posthog
 
     public bool ProjectTokenIsSet { get; private set; }
 
-    public bool PersonalApiKeyIsSet { get; private set; }
+    public bool SecretKeyIsSet { get; private set; }
 
     public bool? NonExistentFlag { get; private set; }
 
@@ -66,7 +66,7 @@ public class IndexModel(IOptions<PostHogOptions> options, IPostHogClient posthog
     public async Task OnGetAsync()
     {
         ProjectTokenIsSet = options.Value.ProjectToken is not (null or []);
-        PersonalApiKeyIsSet = options.Value.PersonalApiKey is not (null or []);
+        SecretKeyIsSet = options.Value.SecretKey is not (null or []);
 
         // Check if the user is authenticated and get their user id.
         UserId = User.Identity?.IsAuthenticated == true

samples/PostHog.Example.Console/.env.example

@@ -4,9 +4,10 @@
 # Your project token (found on the /project/settings page in PostHog)
 POSTHOG_PROJECT_TOKEN=phc_your_project_token_here
 
-# Your personal API key (for local evaluation and other advanced features)
+# Your secret key (for local evaluation and other advanced features)
+# Accepts either a Personal API Key (phx_...) or a Project Secret API Key (phs_...)
 # Found on https://us.posthog.com/settings/user-api-keys
-POSTHOG_PERSONAL_API_KEY=phx_your_personal_api_key_here
+POSTHOG_SECRET_KEY=phx_your_secret_key_here
 
 # PostHog host URL (default is US cloud)
 # Use https://eu.i.posthog.com for EU cloud

samples/PostHog.Example.Console/Program.cs

@@ -28,7 +28,7 @@
 // Get configuration from environment variables
 var projectToken = Environment.GetEnvironmentVariable("POSTHOG_PROJECT_TOKEN")
                    ?? Environment.GetEnvironmentVariable("POSTHOG_PROJECT_API_KEY");
-var personalApiKey = Environment.GetEnvironmentVariable("POSTHOG_PERSONAL_API_KEY");
+var secretKey = Environment.GetEnvironmentVariable("POSTHOG_SECRET_KEY");
 var endpoint = Environment.GetEnvironmentVariable("POSTHOG_HOST") ?? "https://us.i.posthog.com";
 
 // Check credentials
@@ -58,15 +58,15 @@
 
 Console.WriteLine("✅ PostHog credentials loaded successfully!");
 Console.WriteLine($"   Project Token: ✅ Configured");
-Console.WriteLine($"   Personal API Key: {(string.IsNullOrEmpty(personalApiKey) ? "❌ Not set (local evaluation disabled)" : "✅ Configured")}");
+Console.WriteLine($"   Secret Key: {(string.IsNullOrEmpty(secretKey) ? "❌ Not set (local evaluation disabled)" : "✅ Configured")}");
 Console.WriteLine($"   Endpoint: {endpoint}");
 Console.WriteLine();
 
 // Create PostHog options
 var options = new PostHogOptions
 {
     ProjectToken = projectToken,
-    PersonalApiKey = personalApiKey,
+    SecretKey = secretKey,
     HostUrl = new Uri(endpoint),
     FlushAt = 1, // Flush immediately for demo purposes
     FlushInterval = TimeSpan.FromSeconds(1)
@@ -87,7 +87,7 @@
 // Display menu
 while (true)
 {
-    ShowMenu(hasPersonalApiKey: !string.IsNullOrEmpty(personalApiKey));
+    ShowMenu(hasSecretKey: !string.IsNullOrEmpty(secretKey));
     var choice = Prompt("\nEnter your choice (1-6): ");
 
     switch (choice)
@@ -102,10 +102,10 @@
             await RunFeatureFlagExamples(posthog);
             break;
         case "4":
-            await RunLocalEvaluationExample(posthog, hasPersonalApiKey: !string.IsNullOrEmpty(personalApiKey));
+            await RunLocalEvaluationExample(posthog, hasSecretKey: !string.IsNullOrEmpty(secretKey));
             break;
         case "5":
-            await RunAllExamples(posthog, hasPersonalApiKey: !string.IsNullOrEmpty(personalApiKey));
+            await RunAllExamples(posthog, hasSecretKey: !string.IsNullOrEmpty(secretKey));
             break;
         case "6":
             Console.WriteLine("👋 Goodbye!");
@@ -131,14 +131,14 @@
     Console.WriteLine();
 }
 
-static void ShowMenu(bool hasPersonalApiKey)
+static void ShowMenu(bool hasSecretKey)
 {
     Console.WriteLine("🦔 PostHog .NET SDK Demo - Choose an example to run:");
     Console.WriteLine();
     Console.WriteLine("1. Capture events");
     Console.WriteLine("2. Identify users");
     Console.WriteLine("3. Feature flags (remote evaluation)");
-    Console.WriteLine($"4. Local evaluation with ETag polling{(hasPersonalApiKey ? "" : " (requires Personal API Key)")}");
+    Console.WriteLine($"4. Local evaluation with ETag polling{(hasSecretKey ? "" : " (requires Secret Key)")}");
     Console.WriteLine("5. Run all examples");
     Console.WriteLine("6. Exit");
 }
@@ -283,17 +283,17 @@ static async Task RunFeatureFlagExamples(PostHogClient posthog)
     }
 }
 
-static async Task RunLocalEvaluationExample(PostHogClient posthog, bool hasPersonalApiKey)
+static async Task RunLocalEvaluationExample(PostHogClient posthog, bool hasSecretKey)
 {
     Console.WriteLine("\n" + new string('=', 60));
     Console.WriteLine("LOCAL EVALUATION WITH ETAG POLLING");
     Console.WriteLine(new string('=', 60));
 
-    if (!hasPersonalApiKey)
+    if (!hasSecretKey)
     {
-        Console.WriteLine("\n⚠️  This example requires a Personal API Key to be set.");
-        Console.WriteLine("   Set POSTHOG_PERSONAL_API_KEY in your .env file.");
-        Console.WriteLine("   Personal API keys can be created at:");
+        Console.WriteLine("\n⚠️  This example requires a Secret Key to be set.");
+        Console.WriteLine("   Set POSTHOG_SECRET_KEY in your .env file.");
+        Console.WriteLine("   Secret keys can be created at:");
         Console.WriteLine("   https://us.posthog.com/settings/user-api-keys");
         return;
     }
@@ -368,12 +368,12 @@ static async Task RunLocalEvaluationExample(PostHogClient posthog, bool hasPerso
     Console.WriteLine("   ✓ Polling stopped");
 }
 
-static async Task RunAllExamples(PostHogClient posthog, bool hasPersonalApiKey)
+static async Task RunAllExamples(PostHogClient posthog, bool hasSecretKey)
 {
     Console.WriteLine("\n🔄 Running all examples…");
 
     await RunCaptureExamples(posthog);
     await RunIdentifyExamples(posthog);
     await RunFeatureFlagExamples(posthog);
-    await RunLocalEvaluationExample(posthog, hasPersonalApiKey);
+    await RunLocalEvaluationExample(posthog, hasSecretKey);
 }

src/PostHog/Api/PostHogApiClient.cs

@@ -217,9 +217,9 @@ public async Task<LocalEvaluationResponse> GetFeatureFlagsForLocalEvaluationAsyn
     async Task<T?> GetAuthenticatedResponseAsync<T>(string relativeUrl, CancellationToken cancellationToken)
     {
         var options = _options.Value ?? throw new InvalidOperationException(nameof(_options));
-        var personalApiKey = options.PersonalApiKey
+        var personalApiKey = options.SecretKey
                              ?? throw new InvalidOperationException(
-                                 "This API requires that a Personal API Key is set.");
+                                 "This API requires that a SecretKey (Personal API Key or Project Secret API Key) is set.");
 
         var endpointUrl = new Uri(HostUrl, relativeUrl);
 
@@ -242,9 +242,9 @@ async Task<LocalEvaluationResponse> GetAuthenticatedResponseWithETagAsync<T>(
         where T : LocalEvaluationApiResult
     {
         var options = _options.Value ?? throw new InvalidOperationException(nameof(_options));
-        var personalApiKey = options.PersonalApiKey
+        var personalApiKey = options.SecretKey
                              ?? throw new InvalidOperationException(
-                                 "This API requires that a Personal API Key is set.");
+                                 "This API requires that a SecretKey (Personal API Key or Project Secret API Key) is set.");
 
         var endpointUrl = new Uri(HostUrl, relativeUrl);
 

src/PostHog/Config/PostHogOptions.cs

@@ -11,6 +11,8 @@ public sealed class PostHogOptions : IOptions<PostHogOptions>
 {
     string? _projectToken;
     string? _projectApiKey;
+    string? _secretKey;
+    string? _personalApiKey;
 
     /// <summary>
     /// The PostHog project token that identifies which project this client works with.
@@ -32,7 +34,8 @@ internal void Normalize()
     {
         _projectToken = _projectToken.NullIfEmpty();
         _projectApiKey = _projectApiKey.NullIfEmpty();
-        PersonalApiKey = PersonalApiKey.NullIfEmpty();
+        _secretKey = _secretKey.NullIfEmpty();
+        _personalApiKey = _personalApiKey.NullIfEmpty();
         HostUrl = HostUrl.NormalizeHostUrl();
     }
 
@@ -47,17 +50,34 @@ public string? ProjectApiKey
     }
 
     /// <summary>
-    /// Optional personal API key for local feature flag evaluation.
+    /// Optional secret key used for local feature flag evaluation and remote config. Accepts either a Personal
+    /// API Key (<c>phx_...</c>) or a Project Secret API Key (<c>phs_...</c>).
     /// </summary>
     /// <remarks>
-    /// You can find this https://us.posthog.com/project/{YOUR_PROJECT_ID}/settings/user-api-keys
+    /// You can find these at https://us.posthog.com/project/{YOUR_PROJECT_ID}/settings/user-api-keys
     /// When developing an ASP.NET Core project locally, we recommend setting this in your user secrets.
     /// <c>
-    /// dotnet user-secrets --project your/project/path.csproj set PostHog:PersonalApiKey YOUR_PERSONAL_API_KEY
+    /// dotnet user-secrets --project your/project/path.csproj set PostHog:SecretKey YOUR_SECRET_KEY
     /// </c>
     /// In other cases, use an appropriate secrets manager, configuration provider, or environment variable.
+    /// When both <see cref="SecretKey"/> and the deprecated <see cref="PersonalApiKey"/> are set,
+    /// <see cref="SecretKey"/> takes precedence.
     /// </remarks>
-    public string? PersonalApiKey { get; set; }
+    public string? SecretKey
+    {
+        get => _secretKey ?? _personalApiKey;
+        set => _secretKey = value;
+    }
+
+    /// <summary>
+    /// Obsolete alias for <see cref="SecretKey"/>.
+    /// </summary>
+    [Obsolete("Use SecretKey instead. SecretKey accepts a Personal API Key or a Project Secret API Key.")]
+    public string? PersonalApiKey
+    {
+        get => _secretKey ?? _personalApiKey;
+        set => _personalApiKey = value;
+    }
 
     /// <summary>
     /// Evaluation contexts for feature flags.
@@ -109,7 +129,7 @@ public string? ProjectApiKey
     public Func<CapturedEvent, CapturedEvent?>? BeforeSend { get; set; }
 
     /// <summary>
-    /// When <see cref="PersonalApiKey"/> is set, this is the interval to poll for feature flags used in
+    /// When <see cref="SecretKey"/> is set, this is the interval to poll for feature flags used in
     /// local evaluation. Default is 30 seconds.
     /// </summary>
     public TimeSpan FeatureFlagPollInterval { get; set; } = TimeSpan.FromSeconds(30);

src/PostHog/Examples.cs

@@ -13,7 +13,7 @@ public static class Examples
     {
         ProjectToken = "<ph_project_token>",
         HostUrl = new Uri("<ph_client_api_host>"),
-        PersonalApiKey = Environment.GetEnvironmentVariable("PostHog__PersonalApiKey"),
+        SecretKey = Environment.GetEnvironmentVariable("PostHog__SecretKey"),
     });
 
     /// <summary>

src/PostHog/Features/FeatureFlagOptions.cs

@@ -25,14 +25,14 @@ public class AllFeatureFlagsOptions
     /// Whether to only evaluate the flag locally. Defaults to <c>false</c>.
     /// </summary>
     /// <remarks>
-    /// Local evaluation requires that <see cref="PostHogOptions.PersonalApiKey"/> is set.
+    /// Local evaluation requires that <see cref="PostHogOptions.SecretKey"/> is set.
     /// </remarks>
     public bool OnlyEvaluateLocally { get; init; }
 
     /// <summary>
     /// The set of person properties used to evaluate feature flags. Required for both local and remote evaluation
     /// when feature flags have conditions based on person properties.
-    /// For local evaluation (when <see cref="PostHogOptions.PersonalApiKey"/> is present and
+    /// For local evaluation (when <see cref="PostHogOptions.SecretKey"/> is present and
     /// <see cref="OnlyEvaluateLocally"/> is <c>true</c>), these properties are used directly.
     /// For remote evaluation, these properties are sent to PostHog's servers and can override stored person properties.
     /// </summary>

src/PostHog/Features/LocalFeatureFlagsLoader.cs

@@ -52,9 +52,9 @@ void StartPollingIfNotStarted()
     /// <exception cref="ApiException">Thrown when the API returns a <c>quota_limited</c> error.</exception>
     public async ValueTask<LocalEvaluator?> GetFeatureFlagsForLocalEvaluationAsync(CancellationToken cancellationToken)
     {
-        if (string.IsNullOrWhiteSpace(options.Value.PersonalApiKey))
+        if (string.IsNullOrWhiteSpace(options.Value.SecretKey))
         {
-            // Local evaluation is not enabled since it requires a personal api key.
+            // Local evaluation is not enabled since it requires a secret key.
             return null;
         }
         if (_localEvaluator is { } localEvaluator)
@@ -72,7 +72,7 @@ void StartPollingIfNotStarted()
     /// <returns>The local evaluator with the feature flags.</returns>
     public async ValueTask<LocalEvaluator?> RefreshAsync(CancellationToken cancellationToken)
     {
-        if (string.IsNullOrWhiteSpace(options.Value.PersonalApiKey))
+        if (string.IsNullOrWhiteSpace(options.Value.SecretKey))
         {
             return null;
         }