Skip to main content

​
API keys

All public developer API requests require an API key passed in the X-API-Key header.
Keys follow the format tor_ + base64url-encoded random bytes.

​
Key types

​
Workspace key

Created from the authenticated Torpedo dashboard. Can send from any verified domain in the workspace.

​
Domain-scoped key

Created from the authenticated Torpedo dashboard with a domain selected. Can only send from that specific domain. Use these for multi-tenant setups or to isolate sending by domain.

​
Test key

A test key lets you try the API on yourself before you send to real users. Create one from Send a test → Create test key on the dashboard or the API keys page.
  • It starts with tor_test_ and expires 24 hours after it’s created.
  • It belongs to the person who created it, and can only send to that person’s own email address and verified phone number. Sending anywhere else returns 403 (422 for Verify).
  • Test emails go out from no-reply@torpedo.co.mz and test SMS from the platform sender, so leave out from, or set it to that sender.
  • Each workspace gets 10 test emails, 5 test SMS and 20 test verifications. After that, requests return 429 with code TEST_QUOTA_EXCEEDED. Test sends don’t use your trial or credits.
  • Test keys can’t send email batches.
  • Verify also accepts sandbox numbers with a test key. They simulate delivery and failure without sending anything.

​
Getting your key

Keys are returned once only at creation time and cannot be retrieved again. If you lose a key:
  1. Revoke it from the dashboard or with DELETE /api/v1/auth/keys/{id}
  2. Create a new one from the dashboard

​
Security best practices

Never expose API keys in client-side code, public repositories, or browser environments. Keys grant full send access on behalf of your domain.
  • Store keys in environment variables (TORPEDO_API_KEY)
  • Use domain-scoped keys when possible — limits blast radius if a key leaks
  • Rotate keys periodically using the revoke + create flow
  • Set up webhooks to monitor for unexpected sending activity