Charchy Senddocs

API keys and security

Test and live keys, full and sending-only permission, locking a key to a domain, keeping keys on the server — and what to do if one leaks.

Anyone holding a live key can send email as your domain and spend your balance.

Kinds of key

Test keyLive key
Starts withchy_test_chy_live_
Sends real emailNever — simulated events, real webhooksYes
fromAny domainYour verified domains only
CostsFree, 1,000 recipients a dayYour plan and credits
Use it inDevelopment, staging, CIProduction

Create keys under API keys in the dashboard. The full key is shown once; afterwards you see only its last four characters and when it was last used. Up to 20 active keys per workspace, live and test together; a revoked key frees its place. You accept the Charchy Send terms before your first live key.

Permission

  • Full — send, read and list emails (GET /v1/emails…), reschedule and cancel them, check usage, upload images.
  • Sending — send, and check usage (GET /v1/usage, which holds no email data). Everything else answers 403 restricted_api_key.

A checkout service that sends receipts needs a sending key; only admin tools need a full one.

Domain lock

A live key can be locked to one domain (test keys can't). It then sends only from that domain; anything else answers 403 restricted_api_key. If the domain is removed from the workspace, the key can't send at all — revoke it and make a new one. Use one locked key per product or brand, so a leak in one can't send as the others.

Keep keys on the server

  • Read the key from an environment variable (e.g. CHARCHY_SEND_KEY) or your host's secret manager.
  • Never put a key in browser JavaScript, a mobile app, a public repository, a committed .env file, logs or error messages.
  • The API sends no CORS headers, on purpose: a request from browser code fails. Let your front end call your server.
  • Never prefix the variable with NEXT_PUBLIC_ (Next.js) or VITE_ (Vite) — those ship the value to every visitor.
  • One key per environment and per service, so you can revoke one without breaking the others.

If a key leaks

  1. Revoke the key under API keys. It stops working at once — the next request answers 401 invalid_api_key.
  2. Create a new key and put it in your server's environment.
  3. Check Emails for anything you didn't send, and your balance.
  4. If the key was in a Git repository, revoking is what matters: removing it from history doesn't un-leak it.

A sudden jump in volume pauses sending automatically (why), which limits a leaked key — but revoke it as soon as you know.

Webhook secrets

Keep your webhook signing secret (whsec_…) in CHARCHY_WEBHOOK_SECRET on the server. If it leaks, Rotate secret in the dashboard; both secrets sign events for 24 hours while you deploy the new one (Webhooks).

On this page