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.

7.5 KB
Raw Blame
"""
External API endpoints for the Conversations product.

These endpoints are used by the CDP worker for workflow actions and can be opened
to third-party developers in the future.
Authenticated via team secret API token passed as a Bearer token in the Authorization header.

This auth path is legacy (#82564 tracks the worker's move to the scoped-JWT internal
route, api/internal.py). Both routes share the handlers in api/ticket_actions.py.
"""

import hashlib
from typing import Any, cast

from django.conf import settings
from django.db.models import Q
from django.http import HttpRequest

from rest_framework import status
from rest_framework.permissions import AllowAny
from rest_framework.request import Request
from rest_framework.response import Response
from rest_framework.throttling import SimpleRateThrottle
from rest_framework.views import APIView

from posthog.auth import ProjectSecretAPIKeyAuthentication
from posthog.models import Team
from posthog.permissions import get_authenticator_scopes, is_authenticated_via_project_secret_api_key

from products.conversations.backend.api.ticket_actions import (
    handle_ticket_get,
    handle_ticket_patch,
    wants_first_customer_message_text,
)
from products.conversations.backend.metrics import LEGACY_TICKET_AUTH_BY_TEAM_COUNTER, TICKET_ACTION_AUTH_COUNTER


class _ExternalTicketThrottle(SimpleRateThrottle):
    """Rate limit by Bearer token (team secret_api_token)."""

    def get_cache_key(self, request, view):
        auth_header = request.headers.get("Authorization", "")
        token = auth_header[7:].strip() if auth_header.startswith("Bearer ") else ""
        ident = hashlib.sha256(token.encode()).hexdigest() if token else self.get_ident(request)
        return self.cache_format % {"scope": self.scope, "ident": ident}


class ExternalTicketBurstThrottle(_ExternalTicketThrottle):
    scope = "external_ticket_burst"
    rate = "120/minute"


class ExternalTicketSustainedThrottle(_ExternalTicketThrottle):
    scope = "external_ticket_sustained"
    rate = "1200/hour"


class ExternalTicketProjectSecretAPIKeyAuthentication(ProjectSecretAPIKeyAuthentication):
    """Returns None instead of raising when the key's team has conversations disabled, so
    such a key is indistinguishable from an unknown token."""

    activity_credential_type = "project_secret_key"
    # A migrated legacy token (#63111) must keep the legacy path: PATCH accepts it there
    # but refuses PSAKs, and the legacy-usage counters would otherwise go silent.
    defer_migrated_team_tokens = True

    def authenticate(self, request: HttpRequest | Request) -> tuple[Any, None] | None:
        result = super().authenticate(request)
        if result is None:
            return None
        team = self.project_secret_api_key.team
        # This AllowAny view never runs ActiveOrganizationPermission, so the organization
        # state must be enforced here or a key outlives its deactivated organization.
        organization = team.organization
        if not team.conversations_enabled or not organization.is_active or organization.is_pending_deletion:
            return None
        return result


def _authenticate_psak_team(request: Request) -> tuple[Team, None] | tuple[None, Response]:
    """Resolve the team from a project secret API key with the ``support_ticket:read`` scope."""
    if not is_authenticated_via_project_secret_api_key(request):
        return None, Response({"error": "Missing or invalid API key"}, status=status.HTTP_401_UNAUTHORIZED)

    authenticator = cast(ExternalTicketProjectSecretAPIKeyAuthentication, request.successful_authenticator)
    key_scopes = set(get_authenticator_scopes(authenticator) or [])
    if "*" not in key_scopes and "support_ticket:read" not in key_scopes:
        return None, Response(
            {"error": "API key missing required scope 'support_ticket:read'"},
            status=status.HTTP_403_FORBIDDEN,
        )

    return authenticator.project_secret_api_key.team, None


def _authenticate_team(request: Request) -> tuple[Team, None] | tuple[None, Response]:
    """Extract Bearer token from Authorization header and validate against team."""
    # Kill switch (#66179): with legacy tokens off, migrated tokens authenticate as PSAKs
    # (the deferral above also goes inert) and never reach here; the rest get a plain 401.
    if not settings.ACCEPT_TEAM_SECRET_TOKENS:
        return None, Response({"error": "Missing or invalid API key"}, status=status.HTTP_401_UNAUTHORIZED)

    auth_header = request.headers.get("Authorization", "")
    if not auth_header.startswith("Bearer "):
        return None, Response({"error": "Missing or invalid Authorization header"}, status=status.HTTP_401_UNAUTHORIZED)

    api_key = auth_header[7:].strip()
    if not api_key:
        return None, Response({"error": "Empty API key"}, status=status.HTTP_401_UNAUTHORIZED)

    # Authenticate against secret_api_token (not api_token) because api_token
    # is the public project key embedded in client-side JS and visible to anyone.
    try:
        team = Team.objects.get(
            Q(secret_api_token=api_key) | Q(secret_api_token_backup=api_key),
            conversations_enabled=True,
        )
    except (Team.DoesNotExist, Team.MultipleObjectsReturned):
        return None, Response({"error": "Invalid API key"}, status=status.HTTP_401_UNAUTHORIZED)

    # Same 401 as an unknown token: a valid secret token must not outlive its
    # deactivated or deletion-pending organization.
    organization = team.organization
    if not organization.is_active or organization.is_pending_deletion:
        return None, Response({"error": "Invalid API key"}, status=status.HTTP_401_UNAUTHORIZED)

    TICKET_ACTION_AUTH_COUNTER.labels(auth_method="secret_api_token", http_method=(request.method or "").lower()).inc()
    LEGACY_TICKET_AUTH_BY_TEAM_COUNTER.labels(team_id=str(team.id)).inc()
    return team, None


class ExternalTicketView(APIView):
    """
    GET /api/conversations/external/ticket/<ticket_id>  — Fetch ticket data
    PATCH /api/conversations/external/ticket/<ticket_id> — Update ticket fields

    GET accepts the team secret_api_token or a project secret API key with the
    ``support_ticket:read`` scope as a Bearer token. PATCH accepts only the team
    secret_api_token.
    """

    authentication_classes = [ExternalTicketProjectSecretAPIKeyAuthentication]
    permission_classes = [AllowAny]
    throttle_classes = [ExternalTicketBurstThrottle, ExternalTicketSustainedThrottle]

    def get(self, request: Request, ticket_id: str) -> Response:
        if is_authenticated_via_project_secret_api_key(request):
            team, error = _authenticate_psak_team(request)
            if not error:
                TICKET_ACTION_AUTH_COUNTER.labels(auth_method="project_secret_api_key", http_method="get").inc()
        else:
            team, error = _authenticate_team(request)
        if error:
            return error

        assert team is not None

        return handle_ticket_get(
            team, ticket_id, include_first_customer_message_text=wants_first_customer_message_text(request)
        )

    def patch(self, request: Request, ticket_id: str) -> Response:
        if is_authenticated_via_project_secret_api_key(request):
            return Response(
                {"error": "Project secret API keys can only read tickets on this route"},
                status=status.HTTP_403_FORBIDDEN,
            )
        team, error = _authenticate_team(request)
        if error:
            return error

        assert team is not None

        return handle_ticket_patch(request, team, ticket_id)