:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
from typing import Any
from django.conf import settings
from django.core.exceptions import ValidationError as DjangoValidationError
from django.http import JsonResponse
from django.utils.text import slugify
from django.views.decorators.csrf import csrf_exempt
from drf_spectacular.utils import extend_schema_field
from rest_framework import serializers, status, viewsets
from rest_framework.exceptions import PermissionDenied
from rest_framework.request import Request
from rest_framework.response import Response
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.shared import UserBasicSerializer
from posthog.api.utils import get_token
from posthog.exceptions import generate_exception_response
from posthog.models.organization import OrganizationMembership
from posthog.models.team.team import Team
from posthog.models.utils import uuid7
from posthog.tasks.early_access_feature import POSTHOG_TEAM_ID, send_events_for_early_access_feature_stage_change
from posthog.utils_cors import cors_response
from products.access_control.backend.facade.user_access_control import UserAccessControl
from products.access_control.backend.models.role import Role
from products.access_control.backend.presentation.access_control import (
AccessControlViewSetMixin,
UserAccessControlSerializerMixin,
)
from products.cdp.backend.internal_events import InternalEventEvent, InternalEventPerson, produce_internal_event
from products.feature_flags.backend.api.feature_flag import (
MinimalFeatureFlagSerializer,
assert_feature_flag_write_scope,
)
from products.feature_flags.backend.encrypted_flag_payloads import REDACTED_PAYLOAD_VALUE
from products.feature_flags.backend.facade.api import clear_feature_enrollment, create_flag, update_flag
from products.feature_flags.backend.facade.filters import set_feature_enrollment
from products.feature_flags.backend.models.feature_flag import FeatureFlag
from products.feature_flags.backend.ownership import FLAG_OWNER_EARLY_ACCESS, assert_flag_available_for, flag_owner_kind
from .models import EarlyAccessFeature
def assert_feature_flag_rbac_access(
user_access_control: UserAccessControl | None,
*,
feature_flag: FeatureFlag | None = None,
) -> None:
"""Early access feature writes create or mutate a linked feature flag through the FeatureFlag
serializer directly, bypassing the FeatureFlag viewset's RBAC gate. Enforce the same feature_flag
access control here so early_access_feature editor access can't be used to write feature flags a
user otherwise couldn't. Pass ``feature_flag`` to check editing that object; omit it to check
creating a new flag (resource level). Fails open when access controls aren't enabled — the checks
resolve to the default editor level."""
if user_access_control is None:
return
has_access = (
user_access_control.check_access_level_for_object(feature_flag, "editor")
if feature_flag is not None
else user_access_control.check_access_level_for_resource("feature_flag", "editor")
)
if not has_access:
raise PermissionDenied("You don't have sufficient permissions to modify the linked feature flag.")
def derive_feature_flag_key(feature_name: str) -> str:
"""Key of the flag auto-created for a feature of this name.
The collision pre-check in validate() and the actual creation in create() must derive the key
identically. If they drift, the pre-check clears a key create() never uses and the collision
resurfaces as an error on "key", the field the form doesn't have.
"""
return slugify(feature_name)
class MinimalEarlyAccessFeatureSerializer(serializers.ModelSerializer):
"""
A more minimal serializer, intended specificaly for non-generally-available features to be provided
to posthog-js via the /early_access_features/ endpoint. Sync with posthog-js's FeaturePreview interface!
The assignee only carries a display name (no user ID or email): the endpoint is public
(project-token auth), so consumers like posthog.com's roadmap can attribute a feature to
its owner without exposing anything else about the person or role.
"""
documentationUrl = serializers.URLField(source="documentation_url")
flagKey = serializers.CharField(source="feature_flag.key", allow_null=True)
payload = serializers.SerializerMethodField()
assignee = serializers.SerializerMethodField()
class Meta:
model = EarlyAccessFeature
fields = [
"id",
"name",
"description",
"stage",
"documentationUrl",
"flagKey",
"payload",
"assignee",
]
read_only_fields = fields
@extend_schema_field(serializers.DictField(help_text="Feature flag payload for this early access feature"))
def get_payload(self, obj):
return obj.payload if obj.payload else {}
@extend_schema_field(
{
"type": "object",
"nullable": True,
"description": "Display name of the person or role this feature is assigned to, e.g. "
'{"type": "user", "name": "Ada Lovelace"} or {"type": "role", "name": "Data Modeling"}.',
"properties": {
"type": {"type": "string", "enum": ["user", "role"]},
"name": {"type": "string"},
},
}
)
def get_assignee(self, obj):
# Callers serializing many features should select_related assigned_user/assigned_role;
# for unassigned features the *_id checks avoid touching the relations entirely.
if obj.assigned_user_id and obj.assigned_user:
name = f"{obj.assigned_user.first_name} {obj.assigned_user.last_name}".strip()
# Users without a set name (common for SSO/invited accounts) would otherwise
# surface an "assigned but nameless" payload, which is worse than no assignee;
# treat them as unassigned rather than exposing a blank name.
if name:
return {"type": "user", "name": name}
return None
if obj.assigned_role_id and obj.assigned_role:
return {"type": "role", "name": obj.assigned_role.name}
return None
class EarlyAccessFeatureSerializer(UserAccessControlSerializerMixin, serializers.ModelSerializer):
feature_flag = MinimalFeatureFlagSerializer(read_only=True)
name = serializers.CharField(
max_length=200,
help_text="The name of the early access feature.",
)
description = serializers.CharField(
required=False,
allow_blank=True,
help_text="A longer description of what this early access feature does, shown to users in the opt-in UI.",
)
stage = serializers.ChoiceField(
choices=EarlyAccessFeature.Stage.choices,
help_text="Lifecycle stage. Valid values: draft, concept, alpha, beta, general-availability, archived. Moving to an active stage (alpha/beta/general-availability) enables the feature flag for opted-in users.",
)
documentation_url = serializers.URLField(
max_length=800,
required=False,
allow_blank=True,
help_text="URL to external documentation for this feature. Shown to users in the opt-in UI.",
)
payload = serializers.SerializerMethodField()
created_by = UserBasicSerializer(
read_only=True,
allow_null=True,
help_text="The user who created this early access feature. Null for features created before creator tracking was added.",
)
assignee = serializers.SerializerMethodField()
class Meta:
model = EarlyAccessFeature
fields = [
"id",
"feature_flag",
"name",
"description",
"stage",
"documentation_url",
"payload",
"created_at",
"created_by",
"assignee",
"user_access_level",
]
read_only_fields = ["id", "feature_flag", "created_at", "created_by"]
@extend_schema_field(serializers.DictField(help_text="Feature flag payload for this early access feature"))
def get_payload(self, obj):
return obj.payload if obj.payload else {}
def to_representation(self, instance: EarlyAccessFeature) -> dict:
representation = super().to_representation(instance)
# The nested flag serializes raw stored filters, where encrypted payload values
# are ciphertext — redact them; early access surfaces never need payload values.
serialized_flag = representation.get("feature_flag")
if serialized_flag and instance.feature_flag and instance.feature_flag.has_encrypted_payloads:
payloads = (serialized_flag.get("filters") or {}).get("payloads")
if payloads:
serialized_flag["filters"]["payloads"] = dict.fromkeys(payloads, REDACTED_PAYLOAD_VALUE)
return representation
@extend_schema_field(
{
"type": "object",
"nullable": True,
"description": 'The person or role responsible for this feature, e.g. {"type": "user", "id": 123} or '
'{"type": "role", "id": "<role uuid>"}. Defaults to the creator. Send null to unassign.',
"properties": {
"type": {"type": "string", "enum": ["user", "role"]},
"id": {"oneOf": [{"type": "integer"}, {"type": "string"}]},
},
}
)
def get_assignee(self, obj):
if obj.assigned_user_id:
return {"type": "user", "id": obj.assigned_user_id}
if obj.assigned_role_id:
return {"type": "role", "id": str(obj.assigned_role_id)}
return None
def _validated_assignee_fields(self, assignee: Any) -> dict:
"""Convert an assignee payload ({"type": "user"|"role", "id": ...} or None) into model field values,
validating that the referenced user/role belongs to this team's organization."""
if assignee is None:
return {"assigned_user_id": None, "assigned_role_id": None}
if (
not isinstance(assignee, dict)
or assignee.get("type") not in ("user", "role")
or assignee.get("id") in (None, "")
):
raise serializers.ValidationError(
{"assignee": 'Expected null or an object of shape {"type": "user" | "role", "id": ...}.'}
)
organization = self.context["get_organization"]()
try:
if assignee["type"] == "user":
if not OrganizationMembership.objects.filter(
user_id=assignee["id"], organization=organization
).exists():
raise serializers.ValidationError(
{"assignee": "Assignee user does not belong to this organization."}
)
return {"assigned_user_id": assignee["id"], "assigned_role_id": None}
if not Role.objects.filter(id=assignee["id"], organization=organization).exists():
raise serializers.ValidationError({"assignee": "Assignee role does not belong to this organization."})
return {"assigned_user_id": None, "assigned_role_id": assignee["id"]}
except (ValueError, TypeError, DjangoValidationError):
raise serializers.ValidationError({"assignee": "Assignee ID is invalid."})
def update(self, instance: EarlyAccessFeature, validated_data: Any) -> EarlyAccessFeature:
# Handle payload separately since SerializerMethodField is read-only
if "payload" in self.initial_data:
payload_value = self.initial_data.get("payload")
validated_data["payload"] = payload_value if payload_value else {}
# Same for assignee, which also diverges from the model fields (assigned_user/assigned_role)
if "assignee" in self.initial_data:
validated_data.update(self._validated_assignee_fields(self.initial_data.get("assignee")))
stage = validated_data.get("stage", None)
rollout_to_all = self.initial_data.get("rollout_to_all", False)
request = self.context["request"]
user_data = UserBasicSerializer(request.user).data if request.user else None
serialized_previous = MinimalEarlyAccessFeatureSerializer(instance).data
# A PATCH that omits stage (e.g. an inline assignee edit) leaves stage as None here; guard so
# it doesn't read as a move to a null stage and enqueue a spurious stage-change task.
if stage is not None and instance.stage != stage:
send_events_for_early_access_feature_stage_change.delay(str(instance.id), instance.stage, stage)
# The branches below each mutate the linked flag's enrollment filters, so they require
# feature_flag:write. A stage change that writes no flag row is intentionally not gated.
if instance.stage != stage and stage == EarlyAccessFeature.Stage.GENERAL_AVAILABILITY and rollout_to_all:
related_feature_flag = instance.feature_flag
if related_feature_flag:
assert_feature_flag_write_scope(
request,
action="early_access_feature.stage_change",
resource_scope="early_access_feature:write",
team_id=instance.team_id,
feature_flag_id=related_feature_flag.id,
)
assert_feature_flag_rbac_access(self.user_access_control, feature_flag=related_feature_flag)
serialized_data_filters = set_feature_enrollment(
related_feature_flag.get_filters(),
None,
groups=[{"properties": [], "rollout_percentage": 100}],
)
update_flag(
related_feature_flag,
{"filters": serialized_data_filters},
team=self.context["get_team"](),
user=request.user,
request=request,
)
elif instance.stage not in EarlyAccessFeature.ActiveStage and stage in EarlyAccessFeature.ActiveStage:
related_feature_flag = instance.feature_flag
if related_feature_flag:
assert_feature_flag_write_scope(
request,
action="early_access_feature.stage_change",
resource_scope="early_access_feature:write",
team_id=instance.team_id,
feature_flag_id=related_feature_flag.id,
)
assert_feature_flag_rbac_access(self.user_access_control, feature_flag=related_feature_flag)
update_flag(
related_feature_flag,
{"filters": set_feature_enrollment(related_feature_flag.get_filters(), True)},
team=self.context["get_team"](),
user=request.user,
request=request,
)
elif stage is not None and (stage not in EarlyAccessFeature.ActiveStage):
related_feature_flag = instance.feature_flag
if related_feature_flag:
assert_feature_flag_write_scope(
request,
action="early_access_feature.stage_change",
resource_scope="early_access_feature:write",
team_id=instance.team_id,
feature_flag_id=related_feature_flag.id,
)
assert_feature_flag_rbac_access(self.user_access_control, feature_flag=related_feature_flag)
clear_feature_enrollment(related_feature_flag.id, team=self.context["get_team"]())
# clear_feature_enrollment loads the flag by id and saves that copy, not this
# instance. Reload the whole row: the response carries version, and a client that
# sends a stale one to a rollout action gets a 409.
related_feature_flag.refresh_from_db()
updated_instance = super().update(instance, validated_data)
serialized_next = MinimalEarlyAccessFeatureSerializer(updated_instance).data
produce_internal_event(
team_id=instance.team_id,
event=InternalEventEvent(
event="$early_access_feature_updated",
distinct_id=str(uuid7()),
properties={
"previous": serialized_previous,
"next": serialized_next,
},
),
person=(
InternalEventPerson(
id=user_data["id"],
properties=user_data,
)
if user_data
else None
),
)
return updated_instance
class EarlyAccessFeatureSerializerCreateOnly(EarlyAccessFeatureSerializer):
feature_flag_id = serializers.IntegerField(
required=False,
write_only=True,
help_text="Optional ID of an existing feature flag to link. If omitted, a new flag is auto-created from the feature name. The flag must not already be linked to another feature, must not belong to another product such as a survey or experiment, must not be group-based, and must not be multivariate.",
)
_create_in_folder = serializers.CharField(required=False, allow_blank=True, write_only=True)
# Override payload to allow writing (parent uses SerializerMethodField which is read-only)
payload = serializers.JSONField(
required=False,
allow_null=False,
default=dict,
help_text="Arbitrary JSON metadata associated with this feature.",
) # type: ignore
class Meta:
model = EarlyAccessFeature
fields = [
"id",
"name",
"description",
"stage",
"documentation_url",
"payload",
"created_at",
"created_by",
"assignee",
"feature_flag_id",
"feature_flag",
"_create_in_folder",
"user_access_level",
]
read_only_fields = ["id", "feature_flag", "created_at", "created_by"]
def validate(self, data):
# PostHog's own dogfooding project requires a description on every new early access feature.
# Scoped to US cloud specifically: project ids are allocated per region, so id 2 is only
# PostHog's own team on US — on EU/DEV/E2E it belongs to an unrelated customer.
is_us_cloud = (settings.CLOUD_DEPLOYMENT or "").upper() == "US"
if is_us_cloud and self.context["team_id"] == POSTHOG_TEAM_ID and not (data.get("description") or "").strip():
raise serializers.ValidationError({"description": "A description is required for early access features."})
feature_flag_id = data.get("feature_flag_id", None)
feature_flag = None
if feature_flag_id:
try:
feature_flag = FeatureFlag.objects.get(pk=feature_flag_id, team_id=self.context["team_id"])
except FeatureFlag.DoesNotExist:
raise serializers.ValidationError("Feature Flag with this ID does not exist")
if feature_flag.features.exists():
raise serializers.ValidationError(
f"Linked feature flag {feature_flag.key} already has a feature attached to it."
)
# The check above keeps one feature per flag; this one keeps out other products.
assert_flag_available_for(feature_flag, product=FLAG_OWNER_EARLY_ACCESS)
if feature_flag.aggregation_group_type_index is not None:
raise serializers.ValidationError(
"Group-based feature flags are not supported for Early Access Features."
)
if len(feature_flag.variants) > 0:
raise serializers.ValidationError(
"Multivariate feature flags are not supported for Early Access Features."
)
elif data.get("name"):
# No flag was chosen, so create() derives one from the name below. Checking the derived
# key here attaches the error to "name", the field this form actually has, instead of
# letting the nested FeatureFlagSerializer raise it on "key", which the form never shows.
feature_flag_key = derive_feature_flag_key(data["name"])
if not feature_flag_key:
# slugify() strips a name with no ASCII alphanumerics down to "", which the flag
# serializer's key regex then rejects.
raise serializers.ValidationError(
{
"name": "A feature flag key can't be built from this name. Rename this feature using letters (a-z) or numbers, or link an existing flag instead."
}
)
existing_flag = FeatureFlag.objects.filter(
key=feature_flag_key, team__project_id=self.context["get_team"]().project_id
).first()
if existing_flag is not None:
# Linking is only advice worth giving when the flag is actually linkable; the check
# above rejects a flag that already has a feature attached, or that another
# product owns.
remedy = (
"Rename this feature."
if flag_owner_kind(existing_flag) is not None
else "Rename this feature, or link the existing flag instead."
)
raise serializers.ValidationError(
{"name": f"A feature flag with the key '{feature_flag_key}' already exists. {remedy}"}
)
return data
def create(self, validated_data):
validated_data["team_id"] = self.context["team_id"]
request = self.context["request"]
validated_data["created_by"] = request.user if request.user.is_authenticated else None
if "assignee" in self.initial_data:
validated_data.update(self._validated_assignee_fields(self.initial_data.get("assignee")))
elif validated_data["created_by"] is not None:
# By default, the feature is assigned to whoever created it
validated_data["assigned_user_id"] = validated_data["created_by"].id
feature_flag_id = validated_data.get("feature_flag_id", None)
default_condition = [
{"properties": [], "rollout_percentage": 0, "variant": None},
]
if feature_flag_id:
feature_flag = FeatureFlag.objects.get(pk=feature_flag_id, team_id=self.context["team_id"])
# Linking claims the flag, which stops other products adopting it, so editor access
# is required whatever the stage. Only the active stage writes the flag row.
assert_feature_flag_rbac_access(self.user_access_control, feature_flag=feature_flag)
if validated_data.get("stage") in EarlyAccessFeature.ActiveStage:
assert_feature_flag_write_scope(
self.context["request"],
action="early_access_feature.create",
resource_scope="early_access_feature:write",
team_id=self.context["team_id"],
feature_flag_id=feature_flag.id,
)
update_flag(
feature_flag,
{"filters": set_feature_enrollment(feature_flag.get_filters(), True)},
team=self.context["get_team"](),
user=self.context["request"].user,
request=self.context["request"],
)
else:
# No existing flag: we create one, which is a flag write.
assert_feature_flag_write_scope(
self.context["request"],
action="early_access_feature.create",
resource_scope="early_access_feature:write",
team_id=self.context["team_id"],
)
assert_feature_flag_rbac_access(self.user_access_control)
feature_flag_key = derive_feature_flag_key(validated_data["name"])
filters: dict[str, Any] = {
"groups": default_condition,
}
if validated_data.get("stage") in EarlyAccessFeature.ActiveStage:
filters = set_feature_enrollment(filters, True)
feature_flag = create_flag(
{
"key": feature_flag_key,
"name": f"Feature Flag for Early Access Feature {validated_data['name']}",
"filters": filters,
"creation_context": "early_access_features",
},
team=self.context["get_team"](),
user=self.context["request"].user,
request=self.context["request"],
)
validated_data["feature_flag_id"] = feature_flag.id
feature: EarlyAccessFeature = super().create(validated_data)
return feature
class EarlyAccessFeatureViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, viewsets.ModelViewSet):
scope_object = "early_access_feature"
queryset = EarlyAccessFeature.objects.select_related(
"feature_flag", "created_by", "assigned_user", "assigned_role"
).all()
def get_serializer_class(self) -> type[serializers.Serializer]:
if self.request.method == "POST":
return EarlyAccessFeatureSerializerCreateOnly
else:
return EarlyAccessFeatureSerializer
def destroy(self, request: Request, *args: Any, **kwargs: Any) -> Response:
instance = self.get_object()
related_feature_flag = instance.feature_flag
if related_feature_flag:
assert_feature_flag_write_scope(
request,
action="early_access_feature.destroy",
team_id=instance.team_id,
feature_flag_id=related_feature_flag.id,
resource_scope="early_access_feature:write",
)
assert_feature_flag_rbac_access(self.user_access_control, feature_flag=related_feature_flag)
clear_feature_enrollment(related_feature_flag.id, team=self.team)
return super().destroy(request, *args, **kwargs)
@csrf_exempt
def early_access_features(request: Request):
token = get_token(None, request)
stages = request.GET.getlist("stage", [EarlyAccessFeature.Stage.BETA])
if not token:
return cors_response(
request,
generate_exception_response(
"early_access_features",
"Project token not provided. You can find your project token in PostHog project settings.",
type="authentication_error",
code="missing_api_key",
status_code=status.HTTP_401_UNAUTHORIZED,
),
)
team = Team.objects.get_team_from_cache_or_token(token)
if team is None:
return cors_response(
request,
generate_exception_response(
"decide",
"Project token invalid. You can find your project token in PostHog project settings.",
type="authentication_error",
code="invalid_api_key",
status_code=status.HTTP_401_UNAUTHORIZED,
),
)
early_access_features = MinimalEarlyAccessFeatureSerializer(
EarlyAccessFeature.objects.filter(team__project_id=team.project_id, stage__in=stages).select_related(
"feature_flag", "assigned_user", "assigned_role"
),
many=True,
).data
return cors_response(request, JsonResponse({"earlyAccessFeatures": early_access_features}))