Developer Portal Overview #

Everything you need to build with eCardWidget lives under Settings → Developers in the dashboard: API keys, the API reference, and webhooks.

API Keys #

Create and manage the keys used to authenticate API requests.

  • A key is shown in full only once, at creation — copy it somewhere safe. Afterward only the first and last few characters are shown.
  • Give each key a label so you can tell integrations apart.
  • Scope each key to just the feature areas it needs. When creating a key, pick a preset (Full access, Directory sync, Send eCards, Read-only) or set each area to Manage / View only / No access. A request outside the key's scope returns 403 naming the blocked area. Scoping a key down is a good way to limit blast radius — e.g. a directory-sync integration only needs Directory: Manage.
  • Edit a key's permissions any time (the pencil action) to tighten or loosen its scope — no need to rotate the credential.
  • The list shows each key's Access (a summary of its scopes) and Last used time.
  • Delete a key to revoke it immediately.
  • Use the key as a Bearer token on every request: Authorization: Bearer YOUR_API_KEY (see Getting Started).
  • Creating keys, editing key permissions, and rotating the webhook signing secret are dashboard-only — for security they cannot be performed with an API key, even a full-access one.

Zapier connections use the key differently (the /zapier/* endpoints, not the Bearer API). That path is not scope-restricted or rate-limited, so a Zapier connection works with any key regardless of its scopes — per-feature scoping + the request throttle apply to the Bearer API only. A key's Last used still reflects Zapier activity.

API Documentation #

Links to the interactive API reference and endpoint details (the same content as reference/openapi.yaml in this repo).

Check what a key can do (introspection) #

Every key can discover its own capabilities at runtime — useful for integrations (and required by the MCP server) that adapt to whatever scope you granted:

curl "https://app.ecardwidget.com/v2/api/key/info" \
  -H "Authorization: Bearer $ECW_API_KEY"

Returns the key's per-area permission levels (none/view/manage), a flattened capabilities list ("ecards:read", "directory:write", …), the rate limit, and usage this hour. It never returns the key value or any other key. See GET /key/info in the API reference.

AI assistants (MCP) #

Connect Claude, Cursor, and other AI assistants to your account with the eCardWidget MCP server — it uses a scoped API key and exposes only the tools that key permits.

Webhooks #

Webhooks push events from eCardWidget to your server in real time. There are two families:

  • ecard_shared — set a Webhook URL here and click Save to receive a POST (User-Agent: eCardWidget Hook) whenever an eCard is sent/shared. Blank disables it.
  • Directory member-change webhooks — subscribe via the API to team-member changes (created / updated / deactivated / deleted) for two-way HR/CRM sync.

This page also has a delivery log: every attempt with its status, response code, the payload we sent, and the response your endpoint returned. You can Replay any delivery to re-run the exact request, or Send test to fire a sample event and confirm your endpoint is reachable.

See Webhooks for both — full payloads, event types, signing, retry schedule, and the subscribe/unsubscribe endpoints.

← PreviousAuthentication & basicsNext →AI Assistants (MCP)
Documentation
Getting Started