Skip to Content
WhatsApp MCPPlan & PhasesOpsClient Onboarding

Runbook — Client Onboarding (stub)

This is a stub. The full runbook is promoted to docs/operations/client-onboarding.md in Phase 4.

What this runbook covers

End-to-end procedure for taking a new client from “approved by the owner” to “actively using the MCP server”, and the inverse for offboarding.

Outline

Pre-flight

  • Confirm written approval from the owner (file the approval ticket / email).
  • Decide the client’s slug (kebab-case, e.g. acme-corp) and which phone numbers they’ll be granted on.

Onboard

  1. admin clients create --name <slug> --display-name "<Display Name>".
  2. For each phone number the client may use: admin grants add --client <client-id> --phone <phone-id> --tools "send_message,get_messages,..." [--daily-cap N].
  3. admin keys mint --client <client-id> --label "<context>" --scopes "tools:<...>,numbers:<...>" [--expires 90d] [--rpm 60] [--daily 250].
  4. Capture the full wamcp_live_... token (printed to stderr, one time only).
  5. Hand the token to the client via a secure channel (1Password share, age-encrypted file, in-person). Never email / chat the raw token.
  6. Send the client: the MCP server URL (https://wa.<yourdomain>/mcp), the granted phone numbers, the allowed tools, and a copy of docs/api/mcp-tools.md.

Verify

  • Confirm the client can tools/list and call ping.
  • Confirm a send_message to a granted number succeeds.
  • Confirm an out-of-scope call (e.g. ungranted tool) returns the expected error.

Rotate

  • Quarterly or on suspicion: admin keys rotate <key-id> [--grace 7d]. Hand the new token over via the secure channel.

Offboard

  1. admin clients disable <client-id> — instantly blocks all auth attempts.
  2. admin keys revoke <key-id> for each of the client’s keys.
  3. admin grants revoke --client <client-id> --phone <phone-id> for each grant.
  4. Notify the client.
  5. Optional: schedule retention bump on messages / audit_log for compliance.

Open items

The full runbook will include screenshots of the admin CLI output, a one-page Markdown handout for new clients, and the exact wording of the secure-handover template.

BackupsIncident Runbook