adding-project-secret-api-key-auth

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.