: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
"""What a caller may read from billing, computed once on PostHog's side.
PostHog holds the users, memberships, key scopes, organization settings and access flags, so it
works out the answer here and billing checks it. The answer travels in the access token as
three claims. `scope` is what the credential holds. `roles` is who the person is in the
organization. `entitlements` is the access level the role and the two flags add up to.
`projects` is the list a project-scoped credential may see, or None for the whole organization.
"""
from __future__ import annotations
from collections.abc import Sequence
from dataclasses import dataclass, field
from enum import Enum
from typing import Any, Optional
from posthog.auth import ProjectSecretAPIKeyAuthentication
from posthog.exceptions_capture import capture_exception
from posthog.models import Organization, OrganizationMembership, Team, User
from posthog.permissions import (
get_authenticator_scoped_team_ids,
get_authenticator_scopes,
get_authenticator_user_credential,
posthog_feature_flag_enabled,
)
from posthog.user_permissions import UserPermissions
from products.access_control.backend.facade.user_access_control import UserAccessControl, visible_teams_for_user
BILLING_READ_SCOPE = "billing:read"
BILLING_WRITE_SCOPE = "billing:write"
OWNER_ONLY_BILLING_FLAG = "owner-only-billing"
# Gates the organization billing API and the MCP tools that call it, until the API is opened up.
ORGANIZATION_BILLING_API_FLAG = "organization-billing-api"
MEMBER_BILLING_USAGE_SPEND_READ_ACCESS_FLAG = "member-billing-usage-spend-read-access"
BILLING_LIMIT_TODAYS_USAGE_FLAG = "billing-limit-todays-usage"
BILLING_LIMIT_TODAYS_USAGE_KEYS = ("posthog_code_credits",)
def _owner_only_billing_enabled(user: User, organization: Organization) -> Optional[bool]:
if not user.distinct_id:
return None
try:
return posthog_feature_flag_enabled(
OWNER_ONLY_BILLING_FLAG,
str(user.distinct_id),
organization_id=organization.id,
)
except Exception as e:
capture_exception(e, {"organization_id": organization.id, "flag": OWNER_ONLY_BILLING_FLAG})
return None
def _member_billing_usage_spend_read_access_enabled(user: User, organization: Organization) -> bool:
if not user.distinct_id:
return False
try:
return (
posthog_feature_flag_enabled(
MEMBER_BILLING_USAGE_SPEND_READ_ACCESS_FLAG,
str(user.distinct_id),
organization_id=organization.id,
)
is True
)
except Exception as e:
capture_exception(e, {"organization_id": organization.id, "flag": MEMBER_BILLING_USAGE_SPEND_READ_ACCESS_FLAG})
return False
def _billing_limit_todays_usage_enabled(user: User, organization: Organization) -> bool:
if not user.distinct_id:
return False
try:
return (
posthog_feature_flag_enabled(
BILLING_LIMIT_TODAYS_USAGE_FLAG,
str(user.distinct_id),
organization_id=organization.id,
)
is True
)
except Exception as e:
capture_exception(e, {"organization_id": organization.id, "flag": BILLING_LIMIT_TODAYS_USAGE_FLAG})
return False
class BillingEntitlement(str, Enum):
"""The three access levels of the organization billing API. Each covers the ones below it."""
MEMBER = "billing:member"
USAGE_READ = "billing:usage_read"
FULL_ACCESS = "billing:full_access"
ENTITLEMENT_LADDER = [BillingEntitlement.MEMBER, BillingEntitlement.USAGE_READ, BillingEntitlement.FULL_ACCESS]
def entitlements_for(level: BillingEntitlement) -> list[str]:
"""Every right a caller at `level` has, as the token lists them. The token names all of a
caller's rights, so billing checks for the one an endpoint needs and no ranking lives anywhere."""
return [e.value for e in ENTITLEMENT_LADDER[: ENTITLEMENT_LADDER.index(level) + 1]]
@dataclass(frozen=True)
class EffectiveBillingGrants:
sub: str
scope: list[str] = field(default_factory=list)
roles: list[str] = field(default_factory=list)
entitlements: list[str] = field(default_factory=list)
projects: Optional[list[int]] = None
# The acting user's analytics id, carried beside the subject rather than inside it: the subject
# has to name the same principal forever, and a user without a distinct id can gain one later.
distinct_id: Optional[str] = None
@property
def grants_anything(self) -> bool:
return bool(self.entitlements)
NO_GRANTS = EffectiveBillingGrants(sub="anonymous")
def _role_name(level: int) -> str:
if level >= OrganizationMembership.Level.OWNER:
return "owner"
if level >= OrganizationMembership.Level.ADMIN:
return "admin"
return "member"
def _entitlement_for_role(user: User, organization: Organization, level: int) -> BillingEntitlement:
"""The access level the role and the two organization flags add up to, the way the flags gate
the app today. Owners always get full access. Admins get full access unless owner-only billing
is on, and an unknown flag state counts as on. Members get the usage read level when the member
read flag is on and owner-only billing is confirmed off."""
if level >= OrganizationMembership.Level.OWNER:
return BillingEntitlement.FULL_ACCESS
owner_only_off = _owner_only_billing_enabled(user, organization) is False
if level >= OrganizationMembership.Level.ADMIN:
return BillingEntitlement.FULL_ACCESS if owner_only_off else BillingEntitlement.MEMBER
if owner_only_off and _member_billing_usage_spend_read_access_enabled(user, organization):
return BillingEntitlement.USAGE_READ
return BillingEntitlement.MEMBER
def _billing_scope_from_credential(scopes: Optional[Sequence[str]]) -> list[str]:
"""The billing scopes a credential holds. Session auth acts with the user's full access, so it
holds `billing:read`. A write scope or `*` implies read, the way APIScopePermission treats
them."""
if scopes is None:
return [BILLING_READ_SCOPE]
scope_set = set(scopes)
if "*" in scope_set or BILLING_WRITE_SCOPE in scope_set:
return [BILLING_READ_SCOPE, BILLING_WRITE_SCOPE]
if BILLING_READ_SCOPE in scope_set:
return [BILLING_READ_SCOPE]
return []
def visible_team_ids(user: User, organization: Organization) -> list[int]:
return list(
visible_teams_for_user(
organization,
UserAccessControl(user=user, organization_id=str(organization.id)),
UserPermissions(user=user),
)
.order_by("id")
.values_list("id", flat=True)
)
def _projects_for_credential(organization: Organization, authenticator: Any) -> tuple[Optional[list[int]], bool]:
"""The projects the credential is scoped to, and whether that is anything at all.
A credential scoped to teams is clipped to the ones in this organization, whatever the role.
None means the credential is not scoped, which is a read of the whole organization: these are
organization endpoints, and a credential bound to projects is what the project-scoped tokens
will carry. What the user can see is a separate question that the reads answer per request
through the team_ids filter, so a member's visibility never widens or shrinks a token, and an
organization with thousands of projects never lists them in one.
"""
scoped = get_authenticator_scoped_team_ids(authenticator)
if scoped is None:
return None, True
organization_team_ids = set(Team.objects.filter(organization=organization).values_list("id", flat=True))
projects = set(scoped) & organization_team_ids
if not projects:
return None, False
return sorted(projects), True
def _credential_may_act_for(authenticator: Any, organization: Organization) -> bool:
credential = get_authenticator_user_credential(authenticator)
if credential is None:
return True
scoped_organizations = credential.scoped_organizations or []
if scoped_organizations and str(organization.id) not in scoped_organizations:
return False
return True
def _grants_for_project_secret_key(authenticator: ProjectSecretAPIKeyAuthentication, organization: Organization):
key = authenticator.project_secret_api_key
sub = f"project_key:{key.id}"
if key.team.organization_id != organization.id:
return EffectiveBillingGrants(sub=sub)
scope = [BILLING_READ_SCOPE] if BILLING_READ_SCOPE in (key.scopes or []) else []
if not scope:
return EffectiveBillingGrants(sub=sub)
return EffectiveBillingGrants(
sub=sub,
scope=scope,
entitlements=entitlements_for(BillingEntitlement.USAGE_READ),
projects=[key.team_id],
)
def effective_billing_grants(
*, organization: Organization, user: Optional[User] = None, authenticator: Any = None
) -> EffectiveBillingGrants:
"""The grants for one request against one organization.
`authenticator` is `request.successful_authenticator`. It is None for session auth, and the
personal key, OAuth or project secret key authenticator otherwise. A project secret key is its
own principal and has no role. Everything else is a user acting through a credential, and the
credential can only narrow what the user could see."""
if isinstance(authenticator, ProjectSecretAPIKeyAuthentication):
return _grants_for_project_secret_key(authenticator, organization)
if user is None or not isinstance(user, User):
return NO_GRANTS
# The uuid, not the distinct id: it is unique, never null and never edited, so the subject names
# the same user for as long as the user exists. The distinct id rides along as its own claim.
sub = f"user:{user.uuid}"
distinct_id = user.distinct_id or None
membership = OrganizationMembership.objects.filter(user=user, organization=organization).only("level").first()
if membership is None:
return EffectiveBillingGrants(sub=sub, distinct_id=distinct_id)
roles = [_role_name(membership.level)]
if not _credential_may_act_for(authenticator, organization):
return EffectiveBillingGrants(sub=sub, roles=roles, distinct_id=distinct_id)
scope = _billing_scope_from_credential(get_authenticator_scopes(authenticator))
if BILLING_READ_SCOPE not in scope:
return EffectiveBillingGrants(sub=sub, roles=roles, distinct_id=distinct_id)
entitlement = _entitlement_for_role(user, organization, membership.level)
projects, anything = _projects_for_credential(organization, authenticator)
if not anything:
return EffectiveBillingGrants(sub=sub, roles=roles, scope=scope, distinct_id=distinct_id)
return EffectiveBillingGrants(
sub=sub,
scope=scope,
roles=roles,
entitlements=entitlements_for(entitlement),
projects=projects,
distinct_id=distinct_id,
)