# Tenants & quotas

> Register your customers as tenants, and cap spend per tenant and per client.

## Tenants

A tenant is one of *your* customers, identified by **your own id** for it
(`external_id`, typically the company's uuid in your system). Nofy never
parses it; it is the key for grouping, credential overrides, quotas and
alerts.

```bash
curl -X POST https://nofy.encipher.co.tz/v2/tenants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "company-uuid-1", "name": "Acme Fuel"}'
```

```json
{
  "tenant_id": "KCrU9UsxCnrc",
  "external_id": "company-uuid-1",
  "created": true
}
```

Sends naming an unknown tenant fail with `400`, so a typo can never create
a tenant that spends. Register first, send second.

!!! tip "Provisioning is idempotent"
    Registering the same `external_id` again returns the existing tenant
    with `"created": false`, so your onboarding flow can call it
    unconditionally.

## Daily quotas

Two caps guard spend, checked in order on every send:

### Tenant quota
One customer over its allowance gets `429` while your other tenants keep
sending.
### Client quota
The cap for your whole application, across every tenant.

Both count messages created in the last 24 hours and answer `429` with a
message naming the limit that was reached:

```json
{
  "detail": "Daily message quota reached for tenant company-uuid-1 (5000/day)"
}
```

No quota configured means no cap.

## Per-credential rate limits

Each channel credential also caps sends *per minute* (defaults: Email 20,
WhatsApp 60, SMS 60, Push 600). Reaching it does not fail the delivery:
the send waits and retries within its own window, so a burst slows down
instead of dropping messages.