From d7af0ce1955aa953b432512c1dd71dfac304b8d6 Mon Sep 17 00:00:00 2001
From: "posthog[bot]" <206114724+posthog[bot]@users.noreply.github.com>
Date: Fri, 21 Aug 2026 22:11:11 +0000
Subject: [PATCH] docs(security): document the public token revocation endpoint

Point exposed customers at the live self-service key-revocation API. The
endpoint (POST /api/revoke_leaked_key) rotates a leaked token and emails the
owner, but nothing linked it, so a security team was routed to PGP email
instead.

Generated-By: PostHog Desktop
Task-Id: deccba38-b983-44c0-a9ef-521c932c7fa9
---
 SECURITY.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/SECURITY.md b/SECURITY.md
index b3c9468..36ce98d 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -9,3 +9,20 @@ We always recommend using the latest version of PostHog to ensure you get all se
 Please report security vulnerabilities to security-reports@posthog.com.
 
 We currently operate a vulnerability disclosure program and reward valid, high quality reports with merch.
+
+## Revoking a Leaked API Key or Token
+
+If a PostHog credential is exposed, revoke it yourself through the public key-revocation API. Send an unauthenticated POST request with the leaked token. If the token matches a real credential, the endpoint revokes it immediately and emails the owner. This covers personal API keys, project secret API keys, and OAuth access and refresh tokens. A revoked OAuth access token also revokes the paired refresh token.
+
+The endpoint checks only the region it runs on. Check both regions if you do not know which one issued the token:
+
+- US: `https://app.posthog.com/api/revoke_leaked_key`
+- EU: `https://eu.posthog.com/api/revoke_leaked_key`
+
+```bash
+curl -X POST https://app.posthog.com/api/revoke_leaked_key \
+  -H 'Content-Type: application/json' \
+  -d '{"token": "LEAKED_TOKEN"}'
+```
+
+A `"found": false` response means the token was not live in that region, not that it is safe everywhere.