Skip to main content

Admin operations: overview

Phoenix supports two tiers of API key:

  • User keys — the default. Can call the org's normal tool set (company, contact, search, agents, connected third-party tools).
  • Admin keys — a separate, narrow surface. While its owner remains an org admin, an admin key exposes only the privileged management tools (invite/remove users, configure integrations, view org consumption); the normal tools are not exposed to it and calling one is refused. If you need both, keep two connections. Available via the MCP endpoint, the admin REST endpoints, and the Power Automate REST facade.

Admin keys are always scoped to a single organization. Their admin tools work only while the user who minted the key still holds an admin role on at least one team in that organization. If they lose the admin role but remain a member, the key is not revoked: over MCP and Power Automate it is treated as an ordinary user key, while the admin REST endpoints reject it. If they lose access to the organization altogether, all of their keys for that organization are revoked and stop authenticating entirely.

Minting an admin key​

  1. Sign in as an org admin (team_memberships.role = 'admin').
  2. Open Organizations → MCP for your org.
  3. Click Generate New Key, name it (e.g. "Zapier admin"), and pick Admin as the scope.
  4. Copy the key. It also stays visible in the keys table afterwards, with an "Admin" badge, so you can retrieve it again later.

If the Admin option is greyed out, your team membership does not have role = 'admin' for this org. Ask an existing admin to promote you.

Security model​

Three checks run on every privileged request:

  1. The key validates against the registry (api_keys_registry).
  2. The key was minted with scope = 'admin'.
  3. The user still has team_memberships.role = 'admin' for this org right now. This recheck happens on every request.

A user counts as an org admin while they hold an admin role on at least one team in the organization. Once that is no longer true — but they are still a member — their admin key is not automatically deleted, though its admin tools stop working: the admin REST endpoints and the Power Automate facade (for the admin tools it exposes) return 403 forbidden_admin_scope, and over MCP the admin tools simply disappear from tools/list. Over MCP and Power Automate the key itself keeps working, falling back to user scope so the ordinary tools it is entitled to become available to it. If instead the user is removed from the organization entirely, every key they hold for it is revoked automatically and stops authenticating. To revoke a key yourself at any time, use the Revoke button in the MCP keys table.

Auditing​

Every privileged action performed via an admin key writes a row to webapp_org_admin_audit_log:

  • actor_user_id — who took the action.
  • api_key_id — which key was used.
  • action — one of invite_user, remove_user, view_consumption, set_integration_credentials, remove_integration_credentials, list_integrations, view_users, view_api_keys, view_consumption_by_api_key.
  • target_type / target_id — what was acted on.
  • metadata — action-specific details (jsonb).
  • ip_address / user_agent — client metadata.

A successful action always logs. A failing action does not log — only completed operations are audited. If the audit insert itself fails, the action still succeeds and the audit failure is reported in the application logs (org-admin audit log error tag).

What admin keys cannot do​

  • Cross-organization actions. The key is bound to a single org via api_keys_registry.organization_slug; admin endpoints derive the org from the key, never from a request parameter.
  • Mint other admin keys via the API. Key creation goes through the webapp; the MCP/API surface does not expose key minting.
  • Bypass HG superadmin tooling. Customer org admins and HG staff are separate audit surfaces (org_admin_audit_log vs. superadmin_audit_log).

Available admin tools​

ToolSurfaceAudit action
admin_invite_userMCP, REST, Power Automateinvite_user
admin_remove_userMCP, REST, Power Automateremove_user
admin_get_consumptionMCP, REST, Power Automateview_consumption
admin_list_integrationsMCP, REST, Power Automatelist_integrations
admin_set_integration_credentialsMCP, REST, Power Automateset_integration_credentials
admin_remove_integration_credentialsMCP, REST, Power Automateremove_integration_credentials
admin_list_usersMCP, REST, Power Automateview_users
admin_list_api_keysMCP, REST, Power Automateview_api_keys
admin_get_consumption_by_api_keyMCP, REST, Power Automateview_consumption_by_api_key

Foundation lands in #1150; user-management tools (#1151), integration-configuration tools (#1152), and the user/key inventory + per-key consumption tools (#1177).