Skip to content

: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.

feat(cdp): import push device tokens into a push channel (#120090)

Daniel Marchuk524464769a48
diff --git a/posthog/api/integration.py b/posthog/api/integration.py
index 2b8935d8d932..a2719dd612f5 100644
--- a/posthog/api/integration.py
+++ b/posthog/api/integration.py
@@ -53,6 +53,12 @@ from posthog.api.integration_email_status_serializers import (
EmailDomainStatusSerializer,
EmailDomainVerificationSerializer,
)
+from posthog.api.integration_push_tokens import (
+ PushTokenImportRequestSerializer,
+ PushTokenImportResponseSerializer,
+ import_push_tokens,
+ push_channel_app_id,
+)
from posthog.api.mixins import ValidatedRequest, validated_request
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.shared import UserBasicSerializer
@@ -131,7 +137,7 @@ from posthog.permissions import (
TimeSensitiveActionPermission,
)
from posthog.ph_client import feature_enabled_or_false
-from posthog.rate_limit import GitHubRepositoryRefreshThrottle
+from posthog.rate_limit import GitHubRepositoryRefreshThrottle, PushTokenImportThrottle
from posthog.tasks.email import send_integration_access_request
from posthog.utils import absolute_uri, is_relative_url
@@ -1529,6 +1535,7 @@ class IntegrationViewSet(
"email_verify",
# Side-effecting POST (emails admins) — a read-only token must not be able to trigger it.
"request_access",
+ "push_tokens",
]
permission_classes = [IntegrationManagementPermission, PersonalConnectionRecentAuthPermission]
# LimitOffsetPagination needs a total order, or Postgres can return a row on neither side of a
@@ -1574,6 +1581,8 @@ class IntegrationViewSet(
def get_throttles(self):
if self.action == "refresh_github_repos":
return [GitHubRepositoryRefreshThrottle(), *super().get_throttles()]
+ if self.action == "push_tokens":
+ return [PushTokenImportThrottle(), *super().get_throttles()]
return super().get_throttles()
def perform_destroy(self, instance: Integration) -> None:
@@ -2678,6 +2687,29 @@ class IntegrationViewSet(
search = query_serializer.validated_data["search"]
return assignees_response(lambda: GitLabIntegration(instance).list_assignees(search))
+ @validated_request(
+ PushTokenImportRequestSerializer,
+ responses={
+ 200: OpenApiResponse(response=PushTokenImportResponseSerializer, description="Import outcome."),
+ 400: OpenApiResponse(description="The rows are invalid, or the integration is not a push channel."),
+ 429: OpenApiResponse(description="Too many imports for this project. Retry after a minute."),
+ },
+ summary="Import push device tokens",
+ description="Register existing device tokens, for example exported from another provider, on this push "
+ "channel. Each token is stored encrypted on its person, as the mobile SDK stores it.",
+ )
+ @action(methods=["POST"], detail=True, url_path="push_tokens")
+ def push_tokens(self, request: ValidatedRequest, **kwargs) -> Response:
+ integration = self.get_object()
+ if not push_channel_app_id(integration):
+ raise ValidationError("Device tokens can only be imported into an APNs or Firebase push channel.")
+ result = import_push_tokens(integration, request.validated_data["subscriptions"])
+ return Response(
+ PushTokenImportResponseSerializer(
+ {"imported": result.imported, "failed_distinct_ids": result.failed_distinct_ids}
+ ).data
+ )
+
@extend_schema(
request=None,
responses={200: EmailDomainVerificationSerializer},
diff --git a/posthog/api/integration_push_tokens.py b/posthog/api/integration_push_tokens.py
new file mode 100644
index 000000000000..82c75e1c8d99
--- /dev/null
+++ b/posthog/api/integration_push_tokens.py
@@ -0,0 +1,108 @@
+import uuid
+import hashlib
+
+from rest_framework import serializers
+
+from posthog.api.capture import capture_batch_internal
+from posthog.dataclasses import frozen
+from posthog.helpers.encrypted_fields import EncryptedFieldMixin
+from posthog.models.integration import Integration
+
+DEVICE_SUBSCRIPTION_PREFIX = "$device_push_subscription_"
+MAX_SUBSCRIPTIONS_PER_REQUEST = 1000
+EVENT_SOURCE = "push_token_import"
+
+
+class PushTokenSubscriptionSerializer(serializers.Serializer):
+ distinct_id = serializers.CharField(max_length=200, help_text="The person's distinct ID in this project.")
+ device_token = serializers.CharField(
+ max_length=4096, help_text="The APNs device token or FCM registration token of one device."
+ )
+
+
+class PushTokenImportRequestSerializer(serializers.Serializer):
+ subscriptions: serializers.ListSerializer = serializers.ListSerializer(
+ child=PushTokenSubscriptionSerializer(),
+ allow_empty=False,
+ max_length=MAX_SUBSCRIPTIONS_PER_REQUEST,
+ help_text=f"Up to {MAX_SUBSCRIPTIONS_PER_REQUEST} devices to register on this push channel. "
+ "List a person once per device.",
+ )
+
+
+class PushTokenImportResponseSerializer(serializers.Serializer):
+ imported = serializers.IntegerField(help_text="Number of devices stored on their person.")
+ failed_distinct_ids = serializers.ListField(
+ child=serializers.CharField(),
+ help_text="Distinct IDs with at least one device that was not stored. Send those rows again.",
+ )
+
+
+@frozen
+class PushTokenImportResult:
+ imported: int
+ failed_distinct_ids: list[str]
+
+
+class _TokenCipher(EncryptedFieldMixin):
+ pass
+
+
+def push_channel_app_id(integration: Integration) -> str | None:
+ if integration.kind == "apns":
+ return integration.config.get("bundle_id") or None
+ if integration.kind == "firebase":
+ return integration.config.get("project_id") or None
+ return None
+
+
+def device_subscription_key(app_id: str, device_token: str) -> str:
+ # Must match deviceSubscriptionKey in the Node push sender, which reads these keys back.
+ digest = hashlib.sha256(device_token.encode("utf-8")).hexdigest()[:16]
+ return f"{DEVICE_SUBSCRIPTION_PREFIX}{app_id}:{digest}"
+
+
+def import_push_tokens(integration: Integration, subscriptions: list[dict[str, str]]) -> PushTokenImportResult:
+ app_id = push_channel_app_id(integration)
+ if not app_id:
+ raise ValueError("This integration is not a push channel.")
+
+ cipher = _TokenCipher()
+ events = []
+ distinct_id_by_uuid: dict[str, str] = {}
+ seen: set[tuple[str, str]] = set()
+ for subscription in subscriptions:
+ distinct_id, device_token = subscription["distinct_id"], subscription["device_token"]
+ if (distinct_id, device_token) in seen:
+ continue
+ seen.add((distinct_id, device_token))
+ event_uuid = str(uuid.uuid4())
+ distinct_id_by_uuid[event_uuid] = distinct_id
+ events.append(
+ {
+ "event": "$set",
+ "distinct_id": distinct_id,
+ "event_uuid": event_uuid,
+ # Encrypted, because the sender ignores a token it cannot decrypt as forged.
+ "properties": {"$set": {device_subscription_key(app_id, device_token): cipher.encrypt(device_token)}},
+ "options": {"process_person_profile": True},
+ }
+ )
+
+ result = capture_batch_internal(
+ events=events,
+ token=integration.team.api_token,
+ event_source=EVENT_SOURCE,
+ process_person_profile=True,
+ )
+ # Capture skips the person update when person processing is disabled, so that device was never stored.
+ skipped = {
+ event_uuid
+ for event_uuid in result.warnings
+ if result.results.get(event_uuid, {}).get("details") == "person_processing_disabled"
+ }
+ failed = {*result.dropped, *result.retried, *result.unaccounted, *skipped}
+ return PushTokenImportResult(
+ imported=len(events) - len(failed),
+ failed_distinct_ids=sorted({distinct_id_by_uuid[event_uuid] for event_uuid in failed}),
+ )
diff --git a/posthog/api/test/test_integration_push_tokens.py b/posthog/api/test/test_integration_push_tokens.py
new file mode 100644
index 000000000000..e01a0f3f6aa4
--- /dev/null
+++ b/posthog/api/test/test_integration_push_tokens.py
@@ -0,0 +1,121 @@
+from typing import Any
+
+from posthog.test.base import APIBaseTest
+from unittest.mock import patch
+
+from parameterized import parameterized
+from rest_framework import status
+
+from posthog.api.capture import CaptureInternalResult
+from posthog.api.integration_push_tokens import MAX_SUBSCRIPTIONS_PER_REQUEST, _TokenCipher
+from posthog.models.integration import Integration
+from posthog.models.organization import Organization, OrganizationMembership
+from posthog.models.team import Team
+
+
+def _capture_dropping(dropped_distinct_ids: set[str], warning_details: dict[str, str] | None = None):
+ captured: list[dict[str, Any]] = []
+
+ def capture(*, events: list[dict[str, Any]], **kwargs: Any) -> CaptureInternalResult:
+ captured.append({"events": events, **kwargs})
+ result = CaptureInternalResult(status_code=200)
+ for event in events:
+ if details := (warning_details or {}).get(event["distinct_id"]):
+ result.warnings.append(event["event_uuid"])
+ result.results[event["event_uuid"]] = {"result": "warning", "details": details}
+ continue
+ lane = result.dropped if event["distinct_id"] in dropped_distinct_ids else result.ok
+ lane.append(event["event_uuid"])
+ return result
+
+ return capture, captured
+
+
+class TestPushTokenImport(APIBaseTest):
+ def setUp(self) -> None:
+ super().setUp()
+ self.organization_membership.level = OrganizationMembership.Level.ADMIN
+ self.organization_membership.save()
+ self.apns = Integration.objects.create(
+ team=self.team,
+ kind="apns",
+ integration_id="TEAM.com.example.app",
+ config={"bundle_id": "com.example.app", "team_id": "TEAM", "key_id": "KEY"},
+ )
+ self.firebase = Integration.objects.create(
+ team=self.team,
+ kind="firebase",
+ integration_id="example-project",
+ config={"project_id": "example-project"},
+ )
+
+ def _import(self, integration_id: int, subscriptions: list[dict[str, str]]):
+ return self.client.post(
+ f"/api/environments/{self.team.pk}/integrations/{integration_id}/push_tokens/",
+ {"subscriptions": subscriptions},
+ format="json",
+ )
+
+ @parameterized.expand([("apns", "com.example.app"), ("firebase", "example-project")])
+ def test_stores_each_device_encrypted_under_the_key_the_sender_reads(self, kind: str, app_id: str) -> None:
+ capture, captured = _capture_dropping(
+ {"user-2"}, {"user-3": "person_processing_disabled", "user-4": "some_other_warning"}
+ )
+ with patch("posthog.api.integration_push_tokens.capture_batch_internal", side_effect=capture):
+ response = self._import(
+ getattr(self, kind).id,
+ [
+ {"distinct_id": "user-1", "device_token": "a1b2c3d4"},
+ {"distinct_id": "user-1", "device_token": "a1b2c3d4"},
+ {"distinct_id": "user-1", "device_token": "second-device"},
+ {"distinct_id": "user-2", "device_token": "dropped-device"},
+ {"distinct_id": "user-3", "device_token": "skipped-device"},
+ {"distinct_id": "user-4", "device_token": "warned-device"},
+ ],
+ )
+
+ assert response.status_code == status.HTTP_200_OK, response.json()
+ assert response.json() == {"imported": 3, "failed_distinct_ids": ["user-2", "user-3"]}
+ [call] = captured
+ assert call["token"] == self.team.api_token
+ assert call["process_person_profile"] is True
+ first = call["events"][0]
+ assert first["event"] == "$set"
+ assert first["distinct_id"] == "user-1"
+ # The digest is what deviceSubscriptionKey in the Node sender computes for "a1b2c3d4".
+ [(key, value)] = first["properties"]["$set"].items()
+ assert key == f"$device_push_subscription_{app_id}:7dcf407fa84a0e05"
+ assert value != "a1b2c3d4"
+ assert _TokenCipher().decrypt(value) == "a1b2c3d4"
+ assert len(call["events"]) == 5
+
+ def test_rejects_an_integration_that_is_not_a_push_channel(self) -> None:
+ slack = Integration.objects.create(team=self.team, kind="slack", integration_id="T1", config={})
+ with patch("posthog.api.integration_push_tokens.capture_batch_internal") as capture:
+ response = self._import(slack.id, [{"distinct_id": "user-1", "device_token": "a1b2c3d4"}])
+ assert response.status_code == status.HTTP_400_BAD_REQUEST
+ capture.assert_not_called()
+
+ def test_cannot_import_into_another_teams_channel(self) -> None:
+ other_team = Team.objects.create(organization=Organization.objects.create(name="other"))
+ other_apns = Integration.objects.create(
+ team=other_team, kind="apns", integration_id="OTHER.app", config={"bundle_id": "com.other.app"}
+ )
+ with patch("posthog.api.integration_push_tokens.capture_batch_internal") as capture:
+ response = self._import(other_apns.id, [{"distinct_id": "user-1", "device_token": "a1b2c3d4"}])
+ assert response.status_code == status.HTTP_404_NOT_FOUND
+ capture.assert_not_called()
+
+ @parameterized.expand(
+ [
+ ("empty", []),
+ ("too_many", [{"distinct_id": "u", "device_token": "t"}] * (MAX_SUBSCRIPTIONS_PER_REQUEST + 1)),
+ ("missing_token", [{"distinct_id": "u"}]),
+ ("blank_distinct_id", [{"distinct_id": "", "device_token": "t"}]),
+ ]
+ )
+ def test_rejects_invalid_rows_without_capturing(self, _name: str, subscriptions: list[dict[str, str]]) -> None:
+ with patch("posthog.api.integration_push_tokens.capture_batch_internal") as capture:
+ response = self._import(self.apns.id, subscriptions)
+ assert response.status_code == status.HTTP_400_BAD_REQUEST
+ capture.assert_not_called()
diff --git a/posthog/rate_limit.py b/posthog/rate_limit.py
index 1ff5b5647e2d..b61924eee76c 100644
--- a/posthog/rate_limit.py
+++ b/posthog/rate_limit.py
@@ -1878,6 +1878,18 @@ class GitHubRepositoryRefreshThrottle(PersonalApiKeyOrUserRateThrottle):
return super().get_cache_key(request, view)
+class PushTokenImportThrottle(PersonalApiKeyOrUserRateThrottle):
+ # Keyed per team, so a large migration cannot flood ingestion by spreading calls across keys.
+ scope = "push_token_import"
+ rate = "60/minute"
+
+ def get_cache_key(self, request, view):
+ team_id = self.safely_get_team_id_from_view(view)
+ if team_id:
+ return self.cache_format % {"scope": self.scope, "ident": f"team_{team_id}"}
+ return super().get_cache_key(request, view)
+
+
class PostHogConnectionForwardThrottle(PersonalApiKeyOrUserRateThrottle):
# Rate limit the synchronous PostHog-connection forward proxy. Each forward holds an API worker
# open while it round-trips to another cell, so a burst of concurrent forwards to a slow target
diff --git a/products/integrations/frontend/generated/api.schemas.ts b/products/integrations/frontend/generated/api.schemas.ts
index fb4ecd73d00f..0e436f2dea33 100644
--- a/products/integrations/frontend/generated/api.schemas.ts
+++ b/products/integrations/frontend/generated/api.schemas.ts
@@ -664,6 +664,31 @@ export interface LinearTeamsResponseApi {
teams: LinearTeamApi[]
}
+export interface PushTokenSubscriptionApi {
+ /**
+ * The person's distinct ID in this project.
+ * @maxLength 200
+ */
+ distinct_id: string
+ /**
+ * The APNs device token or FCM registration token of one device.
+ * @maxLength 4096
+ */
+ device_token: string
+}
+
+export interface PushTokenImportRequestApi {
+ /** Up to 1000 devices to register on this push channel. List a person once per device. */
+ subscriptions: PushTokenSubscriptionApi[]
+}
+
+export interface PushTokenImportResponseApi {
+ /** Number of devices stored on their person. */
+ imported: number
+ /** Distinct IDs with at least one device that was not stored. Send those rows again. */
+ failed_distinct_ids: string[]
+}
+
export interface SlackUserApi {
/** Slack member ID (e.g. U0123ABC) — post to it to open a direct message. */
id: string
diff --git a/products/integrations/frontend/generated/api.ts b/products/integrations/frontend/generated/api.ts
index e917b18a6d7c..b15714e51df5 100644
--- a/products/integrations/frontend/generated/api.ts
+++ b/products/integrations/frontend/generated/api.ts
@@ -47,6 +47,8 @@ import type {
PostHogConnectionForwardApi,
PostHogConnectionForwardResponseApi,
PostHogConnectionTargetApi,
+ PushTokenImportRequestApi,
+ PushTokenImportResponseApi,
RoleExternalReferenceApi,
RoleExternalReferencesListParams,
RoleExternalReferencesLookupRetrieveParams,
@@ -795,6 +797,28 @@ export const integrationsLinkedinAdsConversionRulesRetrieve = async (
})
}
+export const getIntegrationsPushTokensCreateUrl = (projectId: string, id: number) => {
+ return `/api/projects/${projectId}/integrations/${id}/push_tokens/`
+}
+
+/**
+ * Register existing device tokens, for example exported from another provider, on this push channel. Each token is stored encrypted on its person, as the mobile SDK stores it.
+ * @summary Import push device tokens
+ */
+export const integrationsPushTokensCreate = async (
+ projectId: string,
+ id: number,
+ pushTokenImportRequestApi: PushTokenImportRequestApi,
+ options?: RequestInit
+): Promise<PushTokenImportResponseApi> => {
+ return apiMutator<PushTokenImportResponseApi>(getIntegrationsPushTokensCreateUrl(projectId, id), {
+ ...options,
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', ...options?.headers },
+ body: JSON.stringify(pushTokenImportRequestApi),
+ })
+}
+
export const getIntegrationsTwilioPhoneNumbersRetrieveUrl = (projectId: string, id: number) => {
return `/api/projects/${projectId}/integrations/${id}/twilio_phone_numbers/`
}
diff --git a/products/integrations/frontend/generated/api.zod.ts b/products/integrations/frontend/generated/api.zod.ts
index 97749d591c46..6252f22e66be 100644
--- a/products/integrations/frontend/generated/api.zod.ts
+++ b/products/integrations/frontend/generated/api.zod.ts
@@ -183,6 +183,31 @@ export const IntegrationsEmailPartialUpdateBody = /* @__PURE__ */ zod
})
.describe('Standard Integration serializer.')
+/**
+ * Register existing device tokens, for example exported from another provider, on this push channel. Each token is stored encrypted on its person, as the mobile SDK stores it.
+ * @summary Import push device tokens
+ */
+export const integrationsPushTokensCreateBodySubscriptionsItemDistinctIdMax = 200
+
+export const integrationsPushTokensCreateBodySubscriptionsItemDeviceTokenMax = 4096
+
+export const IntegrationsPushTokensCreateBody = /* @__PURE__ */ zod.object({
+ subscriptions: zod
+ .array(
+ zod.object({
+ distinct_id: zod
+ .string()
+ .max(integrationsPushTokensCreateBodySubscriptionsItemDistinctIdMax)
+ .describe("The person's distinct ID in this project."),
+ device_token: zod
+ .string()
+ .max(integrationsPushTokensCreateBodySubscriptionsItemDeviceTokenMax)
+ .describe('The APNs device token or FCM registration token of one device.'),
+ })
+ )
+ .describe('Up to 1000 devices to register on this push channel. List a person once per device.'),
+})
+
/**
* Unified endpoint for generating Domain Connect apply URLs.
*
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 1cde3b0ff299..5c88e6fa4bf0 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -98179,6 +98179,31 @@ export namespace Schemas {
pins: PulsePin[];
}
+ export interface PushTokenSubscription {
+ /**
+ * The person's distinct ID in this project.
+ * @maxLength 200
+ */
+ distinct_id: string;
+ /**
+ * The APNs device token or FCM registration token of one device.
+ * @maxLength 4096
+ */
+ device_token: string;
+ }
+
+ export interface PushTokenImportRequest {
+ /** Up to 1000 devices to register on this push channel. List a person once per device. */
+ subscriptions: PushTokenSubscription[];
+ }
+
+ export interface PushTokenImportResponse {
+ /** Number of devices stored on their person. */
+ imported: number;
+ /** Distinct IDs with at least one device that was not stored. Send those rows again. */
+ failed_distinct_ids: string[];
+ }
+
export interface QualtricsFeedbackSignalExtra {
survey_id: string | null;
recorded_date: string | null;