How do I revoke PocketHog's access to PostHog?

Revoke PocketHog from your PostHog account settings in a browser. Next time PocketHog tries to refresh its token, the refresh will fail and the app will walk you back to the sign-in screen.

I'm already signed in with an API key — do I have to switch?

No. Your existing API key setup continues to work. PocketHog shows a one-tap migration banner on the home screen suggesting OAuth, but you can dismiss it. Migration preserves your projects, widgets, favorites, and cached data.

Where does PocketHog store my OAuth tokens?

In the iOS App Group Keychain, which is encrypted at rest and protected by your device passcode. Tokens are marked ThisDeviceOnly — excluded from iCloud Keychain backup so they don't roam between devices. PocketHog has no servers and never sees your tokens.

April 18, 2026

Sign in with PostHog — How PocketHog's One-Tap OAuth Works

Q: Can I sign in to PostHog on my iPhone without an API key?

Yes. PocketHog 2.0 adds one-tap 'Sign in with PostHog' using OAuth 2.0. Tap the button, authorize in the sheet that appears, and you're in. No Personal API key needed. Both US Cloud and EU Cloud are supported.

Q: Is PostHog OAuth safe?

OAuth is structurally safer than a hand-pasted API key. PocketHog never sees your PostHog password — authorization happens in a system-provided web sheet (ASWebAuthenticationSession). The tokens are scoped to what you grant on PostHog's consent screen, can be revoked from your PostHog account settings at any time, and are stored only in your device Keychain.

Q: What scopes does PocketHog request?

PocketHog requests openid, profile, organization:read, project:read, query:read, event_definition:read, annotation:read, and annotation:write. You decide which projects or organizations the grant covers on PostHog's consent screen.

Q: Does PocketHog work with self-hosted PostHog?

Self-hosted PostHog users continue to use a Personal API key. OAuth is available for PostHog Cloud (US and EU) in 2.0. You can still use PocketHog with a self-hosted instance by tapping 'Use API key instead' on the sign-in screen and entering your custom host URL.

Until 2.0, getting started with PocketHog meant one annoying thing: creating a Personal API key in PostHog, picking the right scopes, copying the key, and pasting it into the app. It worked, but it was friction, and every new person who tried PocketHog hit that wall before they saw any of their analytics.

2.0 removes the wall. You sign in with PostHog in one tap — pick US Cloud or EU Cloud, authorize in the system sheet that appears, and the app loads your projects. The old API key path is still there if you want it (it's actually required for self-hosted PostHog), but you don't have to use it.

This post is for people who want to understand what actually happens under the hood, what scopes get granted, and why OAuth is a meaningful upgrade over a hand-pasted token.

What changed

The sign-in screen now has two big buttons — one labeled "Sign in with US Cloud", one "Sign in with EU Cloud" — and a small link underneath for people who prefer to paste a Personal API key. That link is also the path for self-hosted PostHog instances.

Tapping either button opens PostHog's hosted authorization page inside an iOS system web view (ASWebAuthenticationSession). You log in with your PostHog credentials — directly to PostHog, not through PocketHog — and review the scopes PocketHog is requesting. PostHog then redirects back to the app with an authorization code, PocketHog exchanges it for an access token and a refresh token, and the main dashboard appears.

That's it from the user's perspective. The parts that make this safer than a pasted API key are everything that happens behind that tap.

Why OAuth is safer than a pasted API key

A PostHog Personal API key grants broad access tied to your account. If you paste it into a third-party app, you're trusting that app to handle it perfectly. Even a well-behaved third party can have a bug that accidentally logs the key, or get compromised in some way outside your control. Rotating a leaked key means regenerating it in PostHog and repasting it everywhere.

OAuth is different in four concrete ways:

PocketHog never sees your password. Authorization happens on PostHog's hosted login page, inside a system-provided web sheet. PocketHog receives a token, not credentials.
Tokens are scoped to what you grant. You review what PocketHog is asking for before you approve, and you can narrow the grant to specific organizations or projects on PostHog's consent screen. The token returned to PocketHog carries that scope.
You can revoke access without changing anything else. Revoking PocketHog in your PostHog account settings invalidates its tokens. You don't need to rotate a key that might be pasted into other apps.
The flow uses PKCE. OAuth 2.0 Authorization Code + PKCE (Proof Key for Code Exchange, S256) — the standard modern protection for native mobile OAuth clients, generated per-flow in CryptoKit so the authorization code can only be exchanged by the app that started the flow.

What scopes PocketHog requests

PocketHog asks for exactly these scopes on the consent screen:

openid, profile — so PocketHog knows which PostHog account it just signed in (for the home screen banner that reads "Connected as your@email.com")
organization:read — list the organizations you belong to, so full-access grants can walk them
project:read — read project metadata (name, token, timezone) for each project you grant access to
query:read — run HogQL queries (used for accurate unique-visitor counts via uniqExact)
event_definition:read — suggest conversion events when you configure a project
annotation:read, annotation:write — read and create chart annotations

PocketHog can do only what those scopes allow. You can narrow the grant further on PostHog's consent screen — full access, a single organization, specific projects, or any subset. PocketHog's dashboard will show just the projects you granted.

Scope-aware project discovery

When the OAuth flow completes, PocketHog looks at the returned token. The token tells it whether you granted full access, a specific set of organizations, or a specific set of projects. Discovery branches on that:

Full access — PocketHog lists the organizations your account belongs to, then lists each organization's projects. Multi-org users see everything they're entitled to, not just the current org.
Organization-scoped — PocketHog fetches projects only for the organizations you granted.
Project-scoped — PocketHog fetches the granted projects directly, in parallel.

If one org or project fails to load (a 403 on a specific resource, for example), discovery records the failure and continues with the rest. You get everything you're actually entitled to, not a dead screen.

Where tokens are stored

Access and refresh tokens live in the iOS App Group Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly. Translated:

App Group — the PocketHog widget extension can read tokens too, so home screen widgets refresh on their own timeline without going through the main app.
AfterFirstUnlock — tokens become readable after you first unlock the device post-reboot, which is what lets widgets work before you open the app.
ThisDeviceOnly — tokens are explicitly excluded from iCloud Keychain backup. Each device pairs with the account it was authorized on.

PocketHog has no servers. Tokens are never transmitted off the device except to PostHog itself.

Token refresh

Access tokens expire. PocketHog handles refresh in two layers:

Proactive. If the app notices a token is within 10 minutes of expiry, it refreshes before making the next API call. Single-flight per region — many concurrent requests don't cause many refreshes.
Lazy-on-401. If a request does come back with a 401, the networking layer triggers a refresh and retries the request once before surfacing the error.

If a refresh fails — the refresh token was revoked, expired, or was invalidated for another reason — PocketHog walks you back to the sign-in screen with an explanation. Nothing is silently broken.

For existing API key users

If you're already using PocketHog with a Personal API key, nothing forces you to switch. The next time you open the app on 2.0 you'll see a non-blocking banner on the home screen suggesting OAuth. Options:

Tap it — walks you through OAuth, then swaps your token store over. Your projects, widgets, favorites, cache, and color schemes are preserved.
Snooze — banner hides for a week, reappears later.
Dismiss — banner never comes back. You continue on API key permanently.

Self-hosted PostHog users should stay on API key — OAuth is Cloud-only in 2.0.

Revoking PocketHog's access

If you ever want to cut PocketHog off from your PostHog account, revoke the authorization from your PostHog account settings in a browser. PocketHog's tokens stop working as soon as the next request fails and can't be refreshed, and the app will return to the sign-in screen. No leftover access.

Frequently asked questions

Can I sign in to PostHog on my iPhone without an API key?

Yes. PocketHog 2.0 adds one-tap Sign in with PostHog using OAuth 2.0. Tap the button, authorize in the sheet, and the app loads your projects. Personal API keys are still supported for people who prefer them or who run self-hosted PostHog.

Is PostHog OAuth safe?

Structurally safer than a Personal API key. PocketHog never sees your password, tokens are scoped to what you grant, and you can revoke access at any time from your PostHog account settings without affecting anything else.

Does PocketHog work with self-hosted PostHog?

Yes, via the Personal API key path. Tap "Use API key instead" on the sign-in screen and enter your self-hosted instance URL.

How do I revoke PocketHog's access?

Revoke PocketHog from your PostHog account settings in a browser. PocketHog's tokens will stop working and the app returns to the sign-in screen.

What scopes does PocketHog request?

openid, profile, organization:read, project:read, query:read, event_definition:read, annotation:read, annotation:write. You decide what the grant actually covers on PostHog's consent screen.

Where does PocketHog store my tokens?

In the iOS App Group Keychain, marked ThisDeviceOnly (excluded from iCloud Keychain backup). PocketHog has no servers — tokens are never transmitted off your device except to PostHog itself.

Get PocketHog

Download PocketHog on the App Store — one-time purchase, $4.99, no subscription.