Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(backend): report OAuth starts and exchange failures to PostHog (#14990)

Krzysztof Czerwinskibae56e70a41b
diff --git a/autogpt_platform/backend/backend/api/features/integrations/oauth_analytics_test.py b/autogpt_platform/backend/backend/api/features/integrations/oauth_analytics_test.py
new file mode 100644
index 0000000000..57e4d681fb
--- /dev/null
+++ b/autogpt_platform/backend/backend/api/features/integrations/oauth_analytics_test.py
@@ -0,0 +1,311 @@
+"""The OAuth login and callback report started / failed to PostHog."""
+
+from unittest.mock import AsyncMock, MagicMock, Mock, patch
+
+import fastapi
+import fastapi.testclient
+import pytest
+from fastapi import HTTPException
+from pydantic import SecretStr
+
+from backend.api.features.integrations.router import router
+from backend.data.model import OAuth2Credentials, OAuthState
+from backend.util import product_analytics
+
+app = fastapi.FastAPI()
+app.include_router(router)
+client = fastapi.testclient.TestClient(app, raise_server_exceptions=False)
+
+ROUTER = "backend.api.features.integrations.router"
+AUTH_CODE = "4/0AVGzR1Bexample-auth-code"
+STATE_TOKEN = "state-token-abc"
+
+
[email protected](autouse=True)
+def setup_auth(mock_jwt_user):
+ from autogpt_libs.auth.jwt_utils import get_jwt_payload
+
+ app.dependency_overrides[get_jwt_payload] = mock_jwt_user["get_jwt_payload"]
+ yield
+ app.dependency_overrides.clear()
+
+
+def capture(monkeypatch: pytest.MonkeyPatch) -> Mock:
+ posthog = Mock()
+ monkeypatch.setattr(product_analytics, "get_posthog_client", lambda: posthog)
+ return posthog.capture
+
+
+def _events(capture: Mock, name: str) -> list[dict]:
+ return [
+ c.kwargs["properties"]
+ for c in capture.call_args_list
+ if c.kwargs["event"] == name
+ ]
+
+
+def _only_failure(capture: Mock) -> dict:
+ failures = _events(capture, "credential_oauth_exchange_failed")
+ assert len(failures) == 1, f"expected 1 failure event, got {len(failures)}"
+ return failures[0]
+
+
+def _state(credential_id: str | None = None) -> OAuthState:
+ return OAuthState(
+ token=STATE_TOKEN,
+ provider="google",
+ expires_at=9999999999,
+ scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+ credential_id=credential_id,
+ )
+
+
+def _google_cred(cred_id: str = "google-cred-1", username: str = "[email protected]"):
+ return OAuth2Credentials(
+ id=cred_id,
+ provider="google",
+ title="My Google",
+ access_token=SecretStr("ya29.access-token"),
+ refresh_token=SecretStr("1//refresh-token"),
+ scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+ username=username,
+ access_token_expires_at=9999999999,
+ )
+
+
+def _handler(exchange: AsyncMock) -> MagicMock:
+ handler = MagicMock()
+ handler.handle_default_scopes.side_effect = lambda scopes: scopes
+ handler.exchange_code_for_tokens = exchange
+ return handler
+
+
+def _post_callback(provider: str = "google"):
+ return client.post(
+ f"/{provider}/callback",
+ json={"code": AUTH_CODE, "state_token": STATE_TOKEN},
+ )
+
+
+class TestOAuthStarted:
+ def test_login_reports_the_provider(self, capture: Mock):
+ handler = MagicMock()
+ handler.get_login_url.return_value = "https://accounts.google.com/auth"
+ with (
+ patch(f"{ROUTER}._get_provider_oauth_handler", return_value=handler),
+ patch(f"{ROUTER}.creds_manager") as mock_mgr,
+ ):
+ mock_mgr.store.store_state_token = AsyncMock(
+ return_value=(STATE_TOKEN, "code-challenge")
+ )
+ resp = client.get("/google/login", params={"scopes": "openid"})
+
+ assert resp.status_code == 200
+ started = _events(capture, "credential_oauth_started")
+ assert len(started) == 1
+ assert started[0]["provider"] == "google"
+ assert started[0]["source"] == "platform"
+
+ def test_login_that_fails_reports_nothing(self, capture: Mock):
+ with patch(
+ f"{ROUTER}._get_provider_oauth_handler",
+ side_effect=HTTPException(status_code=501, detail="not configured"),
+ ):
+ resp = client.get("/google/login")
+
+ assert resp.status_code == 501
+ capture.assert_not_called()
+
+
+class TestOAuthExchangeFailed:
+ def test_invalid_state(self, capture: Mock):
+ with patch(f"{ROUTER}.creds_manager") as mock_mgr:
+ mock_mgr.store.verify_state_token = AsyncMock(return_value=None)
+ resp = _post_callback()
+
+ assert resp.status_code == 400
+ failure = _only_failure(capture)
+ assert failure["provider"] == "google"
+ assert failure["failure_class"] == "invalid_state"
+ assert failure["status_code"] == 400
+ assert failure["detail"] == "Invalid or expired state token"
+
+ def test_provider_unavailable(self, capture: Mock):
+ unconfigured = HTTPException(
+ status_code=501,
+ detail={
+ "message": "Integration with provider 'google' is not configured.",
+ "hint": "Set client ID and secret",
+ },
+ )
+ with (
+ patch(f"{ROUTER}._get_provider_oauth_handler", side_effect=unconfigured),
+ patch(f"{ROUTER}.creds_manager") as mock_mgr,
+ ):
+ mock_mgr.store.verify_state_token = AsyncMock(return_value=_state())
+ resp = _post_callback()
+
+ assert resp.status_code == 501
+ failure = _only_failure(capture)
+ assert failure["failure_class"] == "provider_unavailable"
+ assert failure["status_code"] == 501
+ assert failure["detail"] == (
+ "Integration with provider 'google' is not configured."
+ )
+
+ def test_token_exchange_reports_the_provider_error(self, capture: Mock):
+ exchange = AsyncMock(
+ side_effect=ValueError("(invalid_grant) Missing code verifier.")
+ )
+ with (
+ patch(
+ f"{ROUTER}._get_provider_oauth_handler",
+ return_value=_handler(exchange),
+ ),
+ patch(f"{ROUTER}.creds_manager") as mock_mgr,
+ ):
+ mock_mgr.store.verify_state_token = AsyncMock(return_value=_state())
+ resp = _post_callback()
+
+ assert resp.status_code == 400
+ failure = _only_failure(capture)
+ assert failure["provider"] == "google"
+ assert failure["failure_class"] == "token_exchange"
+ assert failure["status_code"] == 400
+ assert failure["detail"] == "ValueError: (invalid_grant) Missing code verifier."
+
+ def test_token_exchange_detail_hides_client_secret_and_code_verifier(
+ self, capture: Mock
+ ):
+ exchange = AsyncMock(
+ side_effect=ValueError(
+ "rejected client_secret=shh verifier=pkce-v with invalid_grant"
+ )
+ )
+ handler = _handler(exchange)
+ handler.client_secret = "shh"
+ state = _state()
+ state.code_verifier = "pkce-v"
+ with (
+ patch(f"{ROUTER}._get_provider_oauth_handler", return_value=handler),
+ patch(f"{ROUTER}.creds_manager") as mock_mgr,
+ ):
+ mock_mgr.store.verify_state_token = AsyncMock(return_value=state)
+ resp = _post_callback()
+
+ assert resp.status_code == 400
+ assert _only_failure(capture)["detail"] == (
+ "ValueError: rejected client_secret=[redacted] "
+ "verifier=[redacted] with invalid_grant"
+ )
+
+ def test_token_exchange_detail_is_truncated_and_carries_no_secrets(
+ self, capture: Mock
+ ):
+ leaky = (
+ f"code {AUTH_CODE} for [email protected] rejected at "
+ "https://oauth2.googleapis.com/token?code=abc&client_secret=shh "
+ "with ya29.a0AfH6SMBx3example9token " + "x" * 400
+ )
+ exchange = AsyncMock(side_effect=ValueError(leaky))
+ with (
+ patch(
+ f"{ROUTER}._get_provider_oauth_handler",
+ return_value=_handler(exchange),
+ ),
+ patch(f"{ROUTER}.creds_manager") as mock_mgr,
+ ):
+ mock_mgr.store.verify_state_token = AsyncMock(return_value=_state())
+ resp = _post_callback()
+
+ assert resp.status_code == 400
+ detail = _only_failure(capture)["detail"]
+ assert len(detail) <= 200
+ assert detail.startswith("ValueError: code [redacted] for [email] rejected")
+ for secret in (
+ AUTH_CODE,
+ "client_secret",
+ "shh",
+ "a0AfH6SMBx3example9token",
+ ):
+ assert secret not in detail
+
+ def test_credential_merge(self, capture: Mock):
+ existing = _google_cred(username="[email protected]")
+ new_cred = _google_cred(username="[email protected]")
+ with (
+ patch(
+ f"{ROUTER}._get_provider_oauth_handler",
+ return_value=_handler(AsyncMock(return_value=new_cred)),
+ ),
+ patch(f"{ROUTER}.creds_manager") as mock_mgr,
+ ):
+ mock_mgr.store.verify_state_token = AsyncMock(
+ return_value=_state(credential_id="google-cred-1")
+ )
+ mock_mgr.store.get_creds_by_id = AsyncMock(return_value=existing)
+ resp = _post_callback()
+
+ assert resp.status_code == 400
+ failure = _only_failure(capture)
+ assert failure["failure_class"] == "credential_merge"
+ assert failure["status_code"] == 400
+ assert failure["detail"] == (
+ "Username mismatch: authenticated as a different user"
+ )
+
+ def test_unexpected_error_reports_only_its_class(self, capture: Mock):
+ with (
+ patch(
+ f"{ROUTER}._get_provider_oauth_handler",
+ return_value=_handler(AsyncMock(return_value=_google_cred())),
+ ),
+ patch(f"{ROUTER}.creds_manager") as mock_mgr,
+ ):
+ mock_mgr.store.verify_state_token = AsyncMock(return_value=_state())
+ mock_mgr.store.get_creds_by_provider = AsyncMock(return_value=[])
+ mock_mgr.create = AsyncMock(
+ side_effect=RuntimeError("db down for [email protected]")
+ )
+ resp = _post_callback()
+
+ assert resp.status_code == 500
+ failure = _only_failure(capture)
+ # The step that raised stays the class. The status comes from the app's
+ # exception handlers, which this router does not know, so it is left out.
+ assert failure["failure_class"] == "credential_merge"
+ assert "status_code" not in failure
+ assert failure["detail"] == "RuntimeError"
+
+ def test_success_reports_connected_and_no_failure(self, capture: Mock):
+ with (
+ patch(
+ f"{ROUTER}._get_provider_oauth_handler",
+ return_value=_handler(AsyncMock(return_value=_google_cred())),
+ ),
+ patch(f"{ROUTER}.creds_manager") as mock_mgr,
+ ):
+ mock_mgr.store.verify_state_token = AsyncMock(return_value=_state())
+ mock_mgr.store.get_creds_by_provider = AsyncMock(return_value=[])
+ mock_mgr.create = AsyncMock()
+ resp = _post_callback()
+
+ assert resp.status_code == 200
+ assert _events(capture, "credential_oauth_exchange_failed") == []
+ connected = _events(capture, "integration_connected")
+ assert len(connected) == 1
+ assert connected[0]["provider"] == "google"
+ assert connected[0]["method"] == "oauth"
+
+ def test_codex_callback_is_not_reported(self, capture: Mock):
+ with (
+ patch(f"{ROUTER}.enforce_codex_access_http", AsyncMock()),
+ patch(f"{ROUTER}.creds_manager") as mock_mgr,
+ ):
+ mock_mgr.store.verify_state_token = AsyncMock(return_value=None)
+ resp = _post_callback("codex")
+
+ assert resp.status_code == 400
+ assert _events(capture, "credential_oauth_exchange_failed") == []
diff --git a/autogpt_platform/backend/backend/api/features/integrations/router.py b/autogpt_platform/backend/backend/api/features/integrations/router.py
index 9fa746211f..aa89340733 100644
--- a/autogpt_platform/backend/backend/api/features/integrations/router.py
+++ b/autogpt_platform/backend/backend/api/features/integrations/router.py
@@ -165,6 +165,9 @@ async def login(
login_url = handler.get_login_url(
requested_scopes, state_token, code_challenge=code_challenge
)
+ product_analytics.track_credential_oauth_started(
+ user_id=user_id, provider=provider.value
+ )
return LoginResponse(login_url=login_url, state_token=state_token)
@@ -341,14 +344,63 @@ async def callback(
) -> CredentialsMetaResponse:
logger.debug(f"Received OAuth callback for provider: {provider}")
+ # Codex completes a ChatGPT device login here rather than a code exchange,
+ # and its login is not reported as an OAuth start either.
if provider == ProviderName.CODEX:
await enforce_codex_access_http(user_id)
+ valid_state = await _verify_callback_state(user_id, state_token, provider)
+ return await _complete_codex_login(user_id, code, valid_state)
+
+ failure_class: product_analytics.OAuthExchangeFailureClass = "invalid_state"
+ # Everything secret we send the provider, in case its error echoes it back.
+ redact = [code, state_token]
+ try:
+ valid_state = await _verify_callback_state(user_id, state_token, provider)
+ if valid_state.code_verifier:
+ redact.append(valid_state.code_verifier)
+
+ failure_class = "provider_unavailable"
+ handler = _get_provider_oauth_handler(request, provider)
+ client_secret = getattr(handler, "client_secret", None)
+ if isinstance(client_secret, str) and client_secret:
+ redact.append(client_secret)
+
+ failure_class = "token_exchange"
+ credentials = await _exchange_code_for_credentials(
+ handler, provider, code, valid_state
+ )
+
+ failure_class = "credential_merge"
+ # TODO: Allow specifying `title` to set on `credentials`
+ credentials = await _merge_or_create_credential(
+ user_id, provider, credentials, valid_state.credential_id
+ )
+ except Exception as e:
+ _track_oauth_exchange_failed(
+ user_id, provider, failure_class, e, redact=tuple(redact)
+ )
+ raise
+
+ logger.debug(
+ f"Successfully processed OAuth callback for user {user_id} "
+ f"and provider {provider.value}"
+ )
+ product_analytics.track_integration_connected(
+ user_id=user_id,
+ provider=provider.value,
+ credential_type=credentials.type,
+ method="oauth",
+ )
+
+ return to_meta_response(credentials)
- # Verify the state token
+
+async def _verify_callback_state(
+ user_id: str, state_token: str, provider: ProviderName
+) -> OAuthState:
valid_state = await creds_manager.store.verify_state_token(
user_id, state_token, provider
)
-
if not valid_state:
report_credential_failure(
logger,
@@ -362,11 +414,15 @@ async def callback(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Invalid or expired state token",
)
+ return valid_state
- if provider == ProviderName.CODEX:
- return await _complete_codex_login(user_id, code, valid_state)
- handler = _get_provider_oauth_handler(request, provider)
+async def _exchange_code_for_credentials(
+ handler: "BaseOAuthHandler",
+ provider: ProviderName,
+ code: str,
+ valid_state: OAuthState,
+) -> OAuth2Credentials:
try:
scopes = valid_state.scopes
logger.debug(f"Retrieved scopes from state token: {scopes}")
@@ -404,25 +460,49 @@ async def callback(
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail=f"OAuth2 callback failed to exchange code for tokens: {str(e)}",
- )
+ ) from e
- # TODO: Allow specifying `title` to set on `credentials`
- credentials = await _merge_or_create_credential(
- user_id, provider, credentials, valid_state.credential_id
- )
+ return credentials
- logger.debug(
- f"Successfully processed OAuth callback for user {user_id} "
- f"and provider {provider.value}"
- )
- product_analytics.track_integration_connected(
- user_id=user_id,
- provider=provider.value,
- credential_type=credentials.type,
- method="oauth",
- )
- return to_meta_response(credentials)
+def _track_oauth_exchange_failed(
+ user_id: str,
+ provider: ProviderName,
+ failure_class: product_analytics.OAuthExchangeFailureClass,
+ error: Exception,
+ redact: tuple[str, ...],
+) -> None:
+ """Report a failed callback to PostHog, which the browser cannot do reliably
+ because its events wait for analytics consent."""
+ try:
+ status_code: int | None
+ if not isinstance(error, HTTPException):
+ # An unexpected error's message can carry anything; keep its class.
+ # The step it happened in stays the failure_class. Its status is set
+ # later by rest_api's exception handlers (ValueError -> 400, ...),
+ # so leave it out rather than guess.
+ status_code = None
+ detail = type(error).__name__
+ else:
+ status_code = error.status_code
+ # Prefer the provider's own error over our wrapper around it.
+ cause = error.__cause__
+ if cause is not None:
+ detail = f"{type(cause).__name__}: {cause}"
+ elif isinstance(error.detail, dict):
+ detail = str(error.detail.get("message", ""))
+ else:
+ detail = str(error.detail)
+ product_analytics.track_credential_oauth_exchange_failed(
+ user_id=user_id,
+ provider=provider.value,
+ failure_class=failure_class,
+ status_code=status_code,
+ detail=detail,
+ redact=redact,
+ )
+ except Exception:
+ logger.warning("Failed to track OAuth exchange failure", exc_info=True)
# ================================================================== #
diff --git a/autogpt_platform/backend/backend/util/posthog_events.py b/autogpt_platform/backend/backend/util/posthog_events.py
index be79e396a6..b566e2d169 100644
--- a/autogpt_platform/backend/backend/util/posthog_events.py
+++ b/autogpt_platform/backend/backend/util/posthog_events.py
@@ -29,6 +29,8 @@ class PostHogEvent(StrEnum):
TRIGGER_FIRED = "trigger_fired"
EXPERT_HIRED = "expert_hired"
INTEGRATION_CONNECTED = "integration_connected"
+ CREDENTIAL_OAUTH_STARTED = "credential_oauth_started"
+ CREDENTIAL_OAUTH_EXCHANGE_FAILED = "credential_oauth_exchange_failed"
# Experts loop: backend/util/funnel_analytics.py
HIRE_FAILED = "hire_failed"
diff --git a/autogpt_platform/backend/backend/util/posthog_events_test.py b/autogpt_platform/backend/backend/util/posthog_events_test.py
index baa3269ef6..b5c94e7e4e 100644
--- a/autogpt_platform/backend/backend/util/posthog_events_test.py
+++ b/autogpt_platform/backend/backend/util/posthog_events_test.py
@@ -18,6 +18,8 @@ LIVE_EVENT_NAMES = {
"trigger_fired",
"expert_hired",
"integration_connected",
+ "credential_oauth_started",
+ "credential_oauth_exchange_failed",
"hire_failed",
"hire_completed",
"writing_style_added",
diff --git a/autogpt_platform/backend/backend/util/product_analytics.py b/autogpt_platform/backend/backend/util/product_analytics.py
index 71941a001b..3aeba77ec0 100644
--- a/autogpt_platform/backend/backend/util/product_analytics.py
+++ b/autogpt_platform/backend/backend/util/product_analytics.py
@@ -27,6 +27,11 @@ Event vocabulary (PostHog event name -> SQL equivalent):
- ``expert_hired`` a user hired an expert from a template.
- ``integration_connected`` a user connected a credential (OAuth or manual).
IntegrationCredential rows by createdByUserId.
+- ``credential_oauth_started`` the backend issued an OAuth login URL. With
+ ``integration_connected`` and the event below it gives
+ started / connected / failed per provider.
+- ``credential_oauth_exchange_failed`` the OAuth callback returned an error, by
+ ``failure_class``. No SQL equivalent: nothing is stored.
``run_agent`` is not the same as a "task": the ``analytics.*`` views count a
copilot-started run through the chat turn that asked for it, so a task is
@@ -39,6 +44,8 @@ Every emitter is best-effort: tracking can never break the work it describes.
"""
import logging
+import re
+from collections.abc import Iterable
from datetime import datetime
from typing import TYPE_CHECKING, Any, Literal
@@ -56,6 +63,25 @@ settings = Settings()
ScheduleTarget = Literal["agent", "autopilot", "expert"]
+# Where an OAuth callback failed. Dashboards and alerts group on these values,
+# so renaming one breaks them.
+OAuthExchangeFailureClass = Literal[
+ "invalid_state", # state token missing, expired or for another provider
+ "provider_unavailable", # no OAuth handler, or client id/secret not set
+ "token_exchange", # the provider rejected the code, or the exchange raised
+ "credential_merge", # the new token could not be stored on an existing one
+]
+
+_DETAIL_MAX_CHARS = 200
+# The patterns below backtrack on long runs, and an error can embed a whole
+# response body, so they only ever see this much of it.
+_DETAIL_SCAN_MAX_CHARS = 2000
+_URL_QUERY_RE = re.compile(r"(https?://[^\s?#]+)[?#]\S*")
+_EMAIL_RE = re.compile(r"[\w.+-]+@[\w-]+(?:\.[\w-]+)+")
+# Long runs with a digit look like codes, tokens or ids; words and exception
+# names do not.
+_TOKEN_RE = re.compile(r"(?=[\w~+=-]*\d)[\w~+=-]{20,}")
+
# Triggers that mean "a person asked for this run now". Schedule and webhook
# runs are reported as schedule_fired / trigger_fired by their own emitters,
# and nested sub-graph runs are an implementation detail of the parent run.
@@ -321,3 +347,49 @@ def track_integration_connected(
"method": method,
},
)
+
+
+def track_credential_oauth_started(*, user_id: str, provider: str) -> None:
+ track(
+ user_id,
+ PostHogEvent.CREDENTIAL_OAUTH_STARTED,
+ {"provider": _enum_value(provider)},
+ )
+
+
+def track_credential_oauth_exchange_failed(
+ *,
+ user_id: str,
+ provider: str,
+ failure_class: OAuthExchangeFailureClass,
+ status_code: int | None,
+ detail: str,
+ redact: Iterable[str] = (),
+) -> None:
+ track(
+ user_id,
+ PostHogEvent.CREDENTIAL_OAUTH_EXCHANGE_FAILED,
+ {
+ "provider": _enum_value(provider),
+ "failure_class": failure_class,
+ "status_code": status_code,
+ "detail": safe_error_detail(detail, redact),
+ },
+ )
+
+
+def safe_error_detail(detail: str, redact: Iterable[str] = ()) -> str:
+ """An error message fit for analytics: no known secrets, query strings,
+ emails or token-like strings, and at most ``_DETAIL_MAX_CHARS`` long."""
+ for secret in redact:
+ if secret:
+ detail = detail.replace(secret, "[redacted]")
+ detail = " ".join(detail.split())
+ if len(detail) > _DETAIL_SCAN_MAX_CHARS:
+ # Drop the word cut in half: a partial token or email would no longer
+ # match the patterns below.
+ detail = detail[:_DETAIL_SCAN_MAX_CHARS].rsplit(" ", 1)[0]
+ detail = _URL_QUERY_RE.sub(r"\1?[redacted]", detail)
+ detail = _EMAIL_RE.sub("[email]", detail)
+ detail = _TOKEN_RE.sub("[redacted]", detail)
+ return detail[:_DETAIL_MAX_CHARS]
diff --git a/autogpt_platform/backend/backend/util/product_analytics_test.py b/autogpt_platform/backend/backend/util/product_analytics_test.py
index a55b6ce227..efc4980913 100644
--- a/autogpt_platform/backend/backend/util/product_analytics_test.py
+++ b/autogpt_platform/backend/backend/util/product_analytics_test.py
@@ -1,5 +1,6 @@
"""Tests for the activation event vocabulary and its emitters."""
+import time
from unittest.mock import Mock
import pytest
@@ -275,3 +276,92 @@ def test_trigger_fired_and_expert_hired(capture: Mock) -> None:
assert trigger.kwargs["properties"]["target"] == "expert"
assert hired.kwargs["event"] == "expert_hired"
assert hired.kwargs["properties"]["template_id"] == "tmpl-1"
+
+
+def test_credential_oauth_started(
+ capture: Mock, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setattr(
+ product_analytics.settings.config, "app_env", AppEnvironment.LOCAL
+ )
+ product_analytics.track_credential_oauth_started(
+ user_id="user-1", provider="google"
+ )
+
+ event, properties = _only_call(capture)
+ assert event == "credential_oauth_started"
+ assert properties == {
+ "environment": "local",
+ "source": "platform",
+ "provider": "google",
+ }
+
+
+def test_credential_oauth_exchange_failed(
+ capture: Mock, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setattr(
+ product_analytics.settings.config, "app_env", AppEnvironment.LOCAL
+ )
+ product_analytics.track_credential_oauth_exchange_failed(
+ user_id="user-1",
+ provider="google",
+ failure_class="token_exchange",
+ status_code=400,
+ detail="InvalidGrantError: (invalid_grant) Missing code verifier.",
+ )
+
+ event, properties = _only_call(capture)
+ assert event == "credential_oauth_exchange_failed"
+ assert properties == {
+ "environment": "local",
+ "source": "platform",
+ "provider": "google",
+ "failure_class": "token_exchange",
+ "status_code": 400,
+ "detail": "InvalidGrantError: (invalid_grant) Missing code verifier.",
+ }
+
+
+ "detail, expected",
+ [
+ (
+ "(invalid_grant) Missing code verifier.",
+ "(invalid_grant) Missing code verifier.",
+ ),
+ ("bad code the-auth-code", "bad code [redacted]"),
+ ("no access for [email protected]", "no access for [email]"),
+ (
+ "POST https://example.com/token?code=abc&secret=def failed",
+ "POST https://example.com/token?[redacted] failed",
+ ),
+ ("got ya29.a0AfH6SMBx3example9token back", "got ya29.[redacted] back"),
+ ("HTTP Error: 400 -\n invalid_request", "HTTP Error: 400 - invalid_request"),
+ ],
+)
+def test_safe_error_detail_removes_secrets(detail: str, expected: str) -> None:
+ assert product_analytics.safe_error_detail(detail, ["the-auth-code"]) == expected
+
+
+def test_safe_error_detail_is_truncated() -> None:
+ assert len(product_analytics.safe_error_detail("word " * 100)) == 200
+
+
+def test_safe_error_detail_is_fast_on_a_huge_body() -> None:
+ body = "a" * 200_000 + " [email protected]"
+ start = time.monotonic()
+ assert product_analytics.safe_error_detail(body) == "a" * 200
+ assert time.monotonic() - start < 1
+
+
+def test_safe_error_detail_drops_a_word_cut_by_the_scan_limit() -> None:
+ # The query string shrinks to a placeholder, which would pull the start of
+ # the cut token into the first 200 characters.
+ url = "https://example.com/token?" + "q" * 1960
+ token = "ya29" + "x" * 40
+ assert len(url) < 2000 < len(url) + 1 + len(token)
+ assert (
+ product_analytics.safe_error_detail(f"{url} {token}")
+ == "https://example.com/token?[redacted]"
+ )
diff --git a/docs/platform/activation-metrics.md b/docs/platform/activation-metrics.md
index 435101c22f..68c0568d90 100644
--- a/docs/platform/activation-metrics.md
+++ b/docs/platform/activation-metrics.md
@@ -75,8 +75,30 @@ Every event carries `environment` and `source: "platform"`.
| — | `agent_run_completed` | A run reaches COMPLETED. | `trigger`, `cost_cents`, `duration_seconds` |
| — | `expert_hired` | A user hires an expert from a template. | `expert_id`, `template_id` |
| — | `integration_connected` | A user connects a credential, by OAuth or by pasting a key. | `provider`, `credential_type`, `method` |
+| — | `credential_oauth_started` | The backend issues an OAuth login URL (`GET /api/integrations/{provider}/login`). Not Codex, which signs in with a device login. | `provider` |
+| — | `credential_oauth_exchange_failed` | `POST /api/integrations/{provider}/callback` returns an error, on any path. Not Codex. | `provider`, `status_code` (unset for an unexpected error), `failure_class`, `detail` (error message or class, secrets removed, at most 200 characters) |
| agent_idle, stale account | *(not events)* | Computed states, see `agent_health` and `user_lifecycle`. | — |
+`credential_oauth_started`, `integration_connected` (`method: oauth`) and
+`credential_oauth_exchange_failed` give started / connected / failed per
+provider. They are sent by the backend so they are not held back by the
+browser's analytics consent. `failure_class` says where the callback failed:
+
+| `failure_class` | Status | Cause |
+| --- | --- | --- |
+| `invalid_state` | 400 | State token missing, expired, or issued for another provider. |
+| `provider_unavailable` | 400 / 404 / 500 / 501 | No OAuth handler for the provider, or its client id and secret are not set. |
+| `token_exchange` | 400 | The provider rejected the code, or the exchange raised. |
+| `credential_merge` | 400 | The new token could not be stored on an existing credential (username or provider mismatch, managed or system credential). |
+
+An unexpected error (not an HTTP error we raise, e.g. a database error) keeps
+the class of the step it happened in, with only the exception class as
+`detail` and no `status_code`: the app's exception handlers pick the response
+status later (`ValueError` is a 400, for example).
+
+A granted scope set narrower than the one requested is not a callback
+failure: the credential is stored and `integration_connected` fires.
+
The pre-existing copilot events (`copilot_message_sent`, `copilot_tool_called`,
...) and billing events (`credit_topup_success`, `subscription_*`) are unchanged.
Every PostHog event, its sender, its properties and whether it is kept,
diff --git a/docs/platform/tracking-plan.md b/docs/platform/tracking-plan.md
index 155c252138..f1ade7011e 100644
--- a/docs/platform/tracking-plan.md
+++ b/docs/platform/tracking-plan.md
@@ -185,6 +185,8 @@ The tour funnel is sent to DataFast today (`tour_start`, `tour_scenario_start`,
| `tab_intro_cta_clicked` | browser | live | `tab`, `cta` | Its primary CTA is used. |
| `tab_intro_dismissed` | browser | live | `tab` | It is dismissed any other way. |
| `integration_connected` | backend | live | `provider`, `credential_type`, `method` | A credential is stored (OAuth, key, device code). |
+| `credential_oauth_started` | backend | live | `provider` | The backend issues an OAuth login URL (`GET /api/integrations/{provider}/login`). Not Codex. |
+| `credential_oauth_exchange_failed` | backend | live | `provider`, `status_code` (unset for an unexpected error), `failure_class` (`invalid_state`, `provider_unavailable`, `token_exchange`, `credential_merge`), `detail` (redacted, at most 200 characters) | `POST /api/integrations/{provider}/callback` returns an error, on any path. Not Codex. |
| `credential_card_never_rendered` | browser | live | `provider`, `failure_class` | A provider is missing from the provider map. |
| `credential_oauth_popup_blocked` | browser | live | `provider`, `failure_class` | Both the popup and the new tab were blocked. |
| `credential_oauth_flow_timed_out` | browser | live | `provider`, `failure_class` | The OAuth flow timed out. |