feat: add SecretKey config, deprecate PersonalApiKey

[turnipdabeets]

Problem

The credential used for local feature flag evaluation and remote config accepts either a Personal API Key (phx_...) or a Project Secret API Key (phs_...). The option that carries it is named PersonalApiKey, which is confusing — it implies only a personal key is valid.

Change

Add a new canonical PostHogOptions.SecretKey property and keep PersonalApiKey as a deprecated alias. Non-breaking.

• SecretKey accepts a Personal API Key or a Project Secret API Key.
• PersonalApiKey is marked [Obsolete("Use SecretKey instead...")] (warning, not error).
• Both are backed by separate fields; the effective value resolves to SecretKey when non-empty, otherwise PersonalApiKey. When both are set, SecretKey wins. This mirrors the existing ProjectToken/ProjectApiKey alias pattern in this file, so all internal consumers read the canonical property and never touch the obsolete member (no obsolete-warning noise under TreatWarningsAsErrors).
• XML docs, user-secrets example, exception messages, and <see cref> references updated to SecretKey.
• Added a changeset (PostHog, minor).

Context

Coordinated rename across the backend SDKs (Slack discussion). Tracks the rename item in PostHog/posthog-js#4046. Mirrors the draft in posthog-python (#727). This PR covers only the rename item.

[github-actions]

posthog-dotnet Compliance Report

Date: 2026-07-07 14:12:33 UTC
Duration: 4481ms

✅ All Tests Passed!

17/17 tests passed

---

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	262ms
Request Payload.Flags Request Uses V2 Query Param	✅	124ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	115ms
Request Payload.Flags Request Omits Authorization Header	✅	113ms
Request Payload.Token In Flags Body Matches Init	✅	110ms
Request Payload.Groups Round Trip	✅	115ms
Request Payload.Groups Default To Empty Object	✅	110ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	112ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	111ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	111ms
Request Lifecycle.No Flags Request On Init Alone	✅	4ms
Request Lifecycle.No Flags Request On Normal Capture	✅	115ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	215ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	115ms
Retry Behavior.Retries Flags On 502	✅	1115ms
Retry Behavior.Retries Flags On 504	✅	1114ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	214ms

[greptile-apps]

Comments Outside Diff (2)

1. src/PostHog/PostHogClient.cs, line 1417-1418 (link)

   The log warning message still references personal_api_key (the deprecated name), but users are now expected to configure SecretKey. When this warning fires, new users who have never seen the old name will be confused about what to set.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

2. tests/UnitTests/Config/RegistrationTests.cs, line 38-89 (link)

   No forward-path config binding test for SecretKey

   Both CanReadConfiguration tests (here and in tests/UnitTests.AspNetCore/RegistrationTests.cs) still load from PostHog:PersonalApiKey and assert via options.SecretKey, which only exercises the backward-compat alias path. There's no test verifying that configuring PostHog:SecretKey directly also works. This matters in practice because users following the updated user-secrets example (PostHog:SecretKey) should have confidence the new config key is properly bound.

_{Reviews (1): Last reviewed commit: "feat: add SecretKey config, deprecate Pe..." | Re-trigger Greptile}

[greptile-apps]

_{Reviews (2): Last reviewed commit: "chore: address Greptile - SecretKey log ..." | Re-trigger Greptile}

[turnipdabeets]

Marked ready for review.

Naming is settled — this is a generic secret_key config that accepts either a Personal API Key or a Project Secret API Key (both coexist; same Authorization: Bearer header). personal_api_key stays as a deprecated config-name alias that forwards into it — not a deprecation of personal keys as a credential. It's a name-level change and is crash-safe with respect to using the key (adds no new error path).

Merge timing still coordinates with the project-secret-key rollout (feature-flagged today) — ready-for-review ≠ merge-now.

[dustinbyrne]

examples still contain references to POSTHOG_PERSONAL_API_KEY/personal_api_key