Skip to main content

Invite User (admin)

Requires admin-scoped API key

This tool is only available when authenticated with an admin-scoped Phoenix API key. User-scoped keys never see it in tools/list and receive 403 forbidden_admin_scope if they try to call it directly. See Admin operations overview for details.

Invite a user to the calling org. The recipient receives a SendGrid magic-link email and must click it to set a password / sign in.

Tool key: admin_invite_user

Parameters​

NameTypeRequiredDefaultDescription
emailstring (RFC 5322)Yes–Email of the invitee. Lower-cased server-side. Max 254 chars.
role"member" | "admin"Yes–Role granted upon accepting the invitation.
namestringNo–Display name (1–255 chars).

Required Integrations​

None.

How It Works​

The tool reuses the existing webapp invitation flow. There is no fork of the magic-link logic.

  1. The org slug is derived from the API key.
  2. The email domain is checked against the disposable-email blocklist.
  3. The default team for the org is resolved (teams.is_default = true).
  4. If a user with this email already has an active membership in this org, the call returns 409 already_member.
  5. If an active invitation already exists for this (email, default_team), the existing invitation is returned (200, idempotent).
  6. Otherwise a new team_invitations row is inserted and the invitation email is sent via SendGrid.
  7. A row is written to webapp_org_admin_audit_log with action invite_user, target_type user, target_id = lowercased email, metadata = { role, invitationId, idempotent? }.

Use Cases​

  • HR-driven onboarding: a Power Automate flow fires when a new employee is added to a SharePoint list and invites them to Phoenix.
  • AI-assisted admin: "Invite jordan@acme.com as a member of Acme" via Claude Desktop with an admin-scoped MCP key.
  • Bulk onboarding scripts: an n8n workflow reads a CSV and emits one call per row.

Example Usage​

MCP JSON-RPC​

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "admin_invite_user",
    "arguments": {
      "email": "newhire@acme.com",
      "role": "member"
    }
  }
}

Response​

{
  "invitationId": "inv_01HXY…",
  "email": "newhire@acme.com",
  "role": "member",
  "expiresAt": "2026-05-05T16:00:00.000Z"
}

Error codes​

CodeTrigger
disposable_emailEmail domain is on the blocklist (e.g., yopmail, mailinator).
already_memberA user with this email is already an active member of the org.
forbidden_admin_scopeKey is user-scoped or the user is no longer an org admin.
org_misconfiguredOrg has no default team (file a bug).

See also​