Adding API Scopes

Adding an API scope

A scope has two parts: an object and an action, as in feature_flag:read. Adding a scope means adding a scope object, such as feature_flag. It gives tokens feature_flag:read and feature_flag:write. posthog/scopes.py is the source of the object list. The frontend type and the MCP OAuth list are generated from it. The picker rows and the groups are kept by hand in frontend/src/lib/scopes.tsx, and a test checks them. They stay in the frontend on purpose: labels, plurals, groups and picker omissions are UI decisions, while posthog/scopes.py decides what exists and what it grants.

Decide if you need a new scope

Most endpoints fit an existing scope, for example insight:read. Add a new scope only for a product area that a person wants to grant or withhold on its own, on a key or an OAuth app. Name its object with a snake_case singular noun, such as feature_flag.

Decide what kind of scope it is

• Public: OAuth lists it, MCP can request it, and the key picker offers it. This is the default.
• Internal: only the server creates tokens with it. Use INTERNAL_API_SCOPE_OBJECTS.
• OAuth-hidden: a person can paste it into a personal API key, but OAuth clients do not see it. Use this for staff-only or unreleased surfaces. Use OAUTH_HIDDEN_SCOPE_OBJECTS.
• Privileged: only PostHog staff can give it to an OAuth app, through Django admin or a data migration. An app that registers itself cannot get it, and the CLI login and the key picker presets never include it. Use this for a scope that a partner app must not grant to itself, such as llm_gateway. Use PRIVILEGED_SCOPES, and set unprivilegedExcluded: true on the picker row.

Then decide two more things, separately from the kind:

• Project secret API keys: a project secret API key is a project credential with no user, for server-to-server calls. Allow the scope on it only when such a caller needs it. The allowed list is PROJECT_SECRET_API_KEY_ALLOWED_API_SCOPE_ACTION, in both posthog/scopes.py and frontend/src/lib/scopes.tsx. Read /adding-project-secret-api-key-auth first.
• Access control: if an organization must be able to restrict the resource per role or per object, add it to ACCESS_CONTROL_RESOURCES in products/access_control/backend/facade/user_access_control.py. Access control resources use scope object names by design, so a viewset's scope_object names both its token scope and its access control resource. Do not give access control a naming or a type of its own. The resource fields of the access control serializers take GRANTABLE_API_SCOPE_OBJECTS as their choices, and the frontend APIScopeObject type is generated from those fields (be careful: the personal API key modal, the OAuth consent screen, CLI login and the key presets also use that type).

To add the scope

1. Declare it in Python. Add the object to the APIScopeObject literal in posthog/scopes.py. If you chose internal, OAuth-hidden or privileged above, also add it to that set.
2. Connect it to its endpoints. Set scope_object = "<object>" on each viewset the scope covers.
   • Standard actions need no extra work: list and retrieve need :read, and create, update and destroy need :write.
   • A custom @action needs required_scopes, for example required_scopes=["<object>:write"]. Use :read if it only reads data, and :write if it changes data. Without it, token requests get a 403.
   • An endpoint set to scope_object = "INTERNAL" accepts only logged-in sessions. Change it to the new object to open it to tokens.
   • Then call each custom action with a personal API key that has only the new scope. No test checks this.
3. Regenerate. Run hogli build:openapi, which carries the object to the frontend type, and hogli build:projections, which updates the OAuth lists of the MCP server and the web app. DO NOT EDIT GENERATED FILES BY HAND.
4. Show it in the pickers. Skip this step for an OAuth-hidden object: no picker shows it, and the tests do not ask for a row or a group. Otherwise, in frontend/src/lib/scopes.tsx:
   • Add a row to API_SCOPES with a sentence-case label and plural (/writing-user-facing-copy). Disable write if no endpoint writes. If the key modal should not offer the object, add a reason to API_SCOPES_OMITTED_FROM_MODAL instead.
   • Add the object to one group in API_SCOPE_GROUPS. See "Choose a group".
5. Let MCP tools request it. For each MCP tool that calls the endpoint, add the scope under scopes: in products/<product>/mcp/tools.yaml.