> ## Documentation Index
> Fetch the complete documentation index at: https://torpedo.co.mz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How API key authentication works in Torpedo

## API keys

All requests to the Torpedo API (except workspace creation) require an API key passed in the `X-API-Key` header.

```bash theme={null}
curl https://api.torpedo.co.mz/api/v1/emails \
  -H "X-API-Key: tor_your_key_here"
```

Keys follow the format `tor_` + base64url-encoded random bytes.

***

## Key types

### Workspace key

Created automatically when you call `POST /api/v1/workspaces`. Can send from **any** verified domain in the workspace.

### Domain-scoped key

Created via `POST /api/v1/auth/keys` with a `domainId`. Can only send from that specific domain. Use these for multi-tenant setups or to isolate sending by domain.

***

## Getting your key

Keys are returned **once only** at creation time and cannot be retrieved again. If you lose a key:

1. Revoke it via `DELETE /api/v1/auth/keys/{id}`
2. Create a new one

***

## Security best practices

<Warning>
  Never expose API keys in client-side code, public repositories, or browser environments. Keys
  grant full send access on behalf of your domain.
</Warning>

* 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