[posthog]

Why

Five SDKs have renamed the configuration option carrying the project credential from apiKey to projectToken, but the setup spec never named the option at all — it said only "project API key/token". The contract therefore does not record which name is canonical, that the old name survives as a deprecated alias, or that the rename stops at the public configuration surface.

Source SDK changes

SDK	PR	Shipped name
posthog-ios	#573	PostHogConfig(projectToken:), deprecated apiKey alias
posthog-flutter	#374	projectToken, plus com.posthog.posthog.PROJECT_TOKEN for native auto-init
posthog-dotnet	#183	ProjectToken, deprecated ProjectApiKey alias
posthog-kmp	#91	projectToken, deprecated apiKey
posthog-android	#835	projectToken, deprecated apiKey

What changed

Three requirements added to openspec/specs/setup/spec.md:

• Project token configuration option name — projectToken is canonical, adapted to platform casing.
• Deprecated project credential alias — any SDK that still names the option apiKey, including ones not yet renamed, adds projectToken and keeps the old name as a deprecated alias that resolves to the same value. That ships in a minor release; the alias can only be dropped in a later major. A compile-time deprecation counts, and a runtime warning is optional. Where a surface accepts both names at once (options objects, provider props, manifest or Info.plist keys), projectToken wins.
• Project token rename stops at the public configuration surface — wire fields (api_key, token) and persisted queue/preference paths are unchanged, so stored data survives the upgrade. Positional first-argument constructors were never affected.

Narrative updates record which SDKs trim the configured value (iOS, Android, Flutter, React Native), and that React Native's PostHogProvider apiKey prop and Unity's ApiKey have not adopted the name yet.

Proposed, applied, and archived on this branch under openspec/changes/archive/2026-10-08-rename-api-key-to-project-token/.

Not yet renamed

• React Native: <PostHogProvider apiKey="…"> is the named surface to rename. posthog-js #5221 changed only the docs and the missing-token error message. The new PostHog(apiKey, options?) constructor and browser init(token, …) take the token positionally, so they are out of scope.
• Unity: PostHogConfig.ApiKey and PostHogSettings.ApiKey.

Both are non-conforming under this spec until they add projectToken with a deprecated alias. That can ship in a minor release.

Uncertainty

• Deprecation signal. iOS, .NET, and Flutter's native auto-init keys log a runtime warning. Android, KMP, and Flutter's Dart apiKey getter use @Deprecated only, so the requirement accepts either, and the alias scenario checks the resolved token, not a log line.
• Both names at once can't happen on iOS, Android, KMP, or Flutter's Dart config (separate constructors), so the precedence scenario is tagged @both_token_names_capable.
• Trimming is in the narrative, not a requirement, and I did not audit every SDK for it.

Validation

openspec validate --specs --strict passes (64 passed, 0 failed), the same as on main. These are specification checks, not executed SDK conformance tests.

---

Created with PostHog Desktop

🤖 Generated with Claude Code