Skip to main content

Admin operations: overview

Phoenix supports two tiers of API key:

  • User keys — the default. Can call any tool exposed for the org.
  • Admin keys — additionally authorized for privileged management operations (invite/remove users, configure integrations, view org consumption). Available via the MCP endpoint and the Power Automate REST facade.

Admin keys are always scoped to a single organization and only work while the user who minted them remains an org admin in that organization.

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's shown once. You'll find it in the keys table with an "Admin" badge.

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.

If the user is demoted, their admin key is not automatically deleted. The next admin call returns 403 forbidden_admin_scope. Regular tool calls with the same key continue to work — only admin endpoints are gated. To fully revoke the key, 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.
  • 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​

This page lists tools as they're released. The foundation lands in #1150; the user-management tools land with PHX-670 and the integration-configuration tools with PHX-671.