OpenParable
Skip to content
← Back to skills

Adding Project Secret API Key Auth

Development
adding-project-secret-api-key-auth

Adding Project Secret API Key Auth is an Agent Skill for development published in the PostHog/posthog repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

How to gate a PostHog API endpoint with project secret API key (PSAK) auth — a project-scoped, user-less service credential. Use when adding PSAK support to a viewset action, allowing a new scope for PSAKs, handling synthetic users (ProjectSecretAPIKeyUser), or choosing PSAK-aware rate throttles. Trigger terms: PSAK, ProjectSecretAPIKey, project secret API key, phs_ token, service auth, programmatic endpoint auth.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/PostHog/posthog/blob/HEAD/.agents/skills/adding-project-secret-api-key-auth/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/adding-project-secret-api-key-auth, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Adding project secret API key (PSAK) auth to an endpoint

What a PSAK is

A ProjectSecretAPIKey is a project-scoped, user-less service credential (posthog/models/project_secret_api_key.py). It behaves like a personal API key but survives users leaving the project, carries its own scopes, and authenticates as a synthetic user — not a real User row.

  • Token format: phs_... (Bearer header only — no body fallback, unlike the legacy token).
  • Scopes are project-wide within their resource type and deliberately ignore object-level access controls (per-resource RBAC).
  • Do not confuse with TeamSecretTokenAuthentication — that validates the legacy per-team Team.secret_api_token (also phs_-prefixed) and is only for feature-flag local evaluation and similar pre-PSAK surfaces. It is pegged for migrating to PSAK at some point.

Keys are managed at POST /api/environments/:id/project_secret_api_keys (label + scopes; plaintext value returned once; roll action to rotate; max 50 per project; wildcard * scope not allowed).

Wiring a viewset action — the checklist

The machinery is shipped but nothing is wired to it yet — the first planned consumer is the endpoints (the product) run action. Four things, all required:

1. Whitelist the scope/action pair

PSAK-assignable scopes are a global allowlist in posthog/scopes.py:

PROJECT_SECRET_API_KEY_ALLOWED_API_SCOPE_ACTION: list[tuple[APIScopeObject, APIScopeActions]] = [("endpoint", "read")]

If your product isn't listed, key creation rejects the scope before auth is ever attempted. Add your (scope_object, action) tuple here first.

2. Add the authenticator and opt in actions

class MyViewSet(TeamAndOrgViewSetMixin, viewsets.ModelViewSet):
    scope_object = "endpoint"
    authentication_classes = [ProjectSecretAPIKeyAuthentication]  # extends, TeamAndOrgViewSetMixin keeps session/PAK auth
    psak_allowed_actions = ["run"]

psak_allowed_actions is default-deny: APIScopePermission rejects any PSAK request whose action isn't listed ("This action does not support project secret API key access"). List only the programmatic actions — never CRUD that should stay human-driven.

APIScopePermission also enforces team binding automatically: a PSAK only works against view.team == key.team, so PSAK auth only makes sense on project-scoped (/api/environments/:id/...) routes.

3. Use PSAK-aware throttles

PersonalApiKeyRateThrottle subclasses silently bypass PSAK requests (no personal key → no throttling). Use the PSAK-aware pair from posthog/rate_limit.py:

  • PersonalOrProjectSecretApiKeyRateThrottle — per-key budget (keyed psak:{key_id}), also still throttles personal keys.
  • ProjectSecretApiKeyTeamRateThrottle — per-team aggregate (keyed psak-team:{team_id}), caps total PSAK load regardless of how many keys a project mints. Stack it alongside the per-key throttle.

Subclass them to set product-specific scope/rate; remember each throttle keeps its own cache bucket per scope string.

4. Handle the synthetic user

request.user is a ProjectSecretAPIKeyUser (a SyntheticUser, posthog/synthetic_user.py), not a User:

  • user.id is None — never use it as a foreign key. Use user.current_team_id.

  • has_perm() always returns False — Django permission checks silently deny.

  • Skip per-object access-control checks for it (PSAK scopes are project-wide by design):

    if is_authenticated_via_project_secret_api_key(request):
        return  # PSAK bypasses object-level RBAC deliberately
    

    Use isinstance(user, ProjectSecretAPIKeyUser) only where no request is in scope.

  • report_user_action drops synthetic users — if you need analytics for PSAK-authenticated calls, capture explicitly with posthoganalytics.capture(distinct_id=user.distinct_id, ...) and include an auth_method property so both paths emit the same event shape.

  • HogQL system tables: Database.create_for hides RBAC-scoped system tables the key's scopes don't cover (via readable_system_table_access_scopes()).

Helpers in posthog/permissions.py when you need to branch: is_authenticated_via_project_secret_api_key(request) and is_service_auth(request) (covers PSAK + legacy team token).

What you get for free

  • Query tagging: the authenticator calls tag_authentication(access_method=AccessMethod.PROJECT_SECRET_API_KEY, api_key_mask=..., api_key_label=...), so ClickHouse query_log attribution works with no per-endpoint code. If you add a new authenticator, tag through tag_authentication (the single funnel in posthog/clickhouse/query_tagging.py) — not with ad-hoc tag_queries calls.
  • last_used_at tracking: updated at most hourly via .update() (bypasses ModelActivityMixin so routine auth doesn't spam the activity log).
  • Activity logging on key create/update/roll/delete.

Calling a PSAK-gated endpoint

curl -s https://us.posthog.com/api/environments/<project_id>/<your_action_path>/ \
  -H "Authorization: Bearer phs_<key>" \
  -H "Content-Type: application/json" \
  -d '{...}'

Testing

Mirror the PSAK sections of posthog/api/test/test_authentication.py, posthog/test/test_permissions.py, and posthog/test/test_rate_limit.py. Cover at minimum:

  • allowed action with correct scope → 200
  • action not in psak_allowed_actions → 403
  • missing/wrong scope → 403
  • key from another team's project → 403
  • non-PSAK auth on the same action still works