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

# Tenant lifecycle

> Update, suspend, and reactivate tenants.

The base tenant endpoints (create, list, get) are under [API Reference → Tenants](/api-reference/endpoint/create). This page covers lifecycle operations available to platform-admin callers.

<Note>
  These endpoints are intended for platform operators, not tenant users. In production, route them through a separate auth boundary (e.g. an internal admin API gateway).
</Note>

## Update tenant

```http theme={null}
PUT /v1/tenants/{id}
```

```bash theme={null}
curl -X PUT https://api.qustody.io/v1/tenants/tnt_01HXYZ \
  -H "Authorization: Bearer $QUSTODY_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Treasury (Renamed)",
    "ip_allowlist": ["203.0.113.0/24"],
    "metadata": {"tier": "enterprise"}
  }'
```

**Updatable fields**

| Field          | Description                            |
| -------------- | -------------------------------------- |
| `name`         | Display name                           |
| `ip_allowlist` | Array of CIDRs; empty = no restriction |
| `metadata`     | Free-form JSON object                  |

**Response 200**

```json theme={null}
{
  "id": "tnt_01HXYZ...",
  "name": "Acme Treasury (Renamed)",
  "status": "active",
  "ip_allowlist": ["203.0.113.0/24"],
  "metadata": {"tier": "enterprise"},
  "updated_at": "2026-04-27T10:15:00Z"
}
```

## Suspend tenant

Marks the tenant `suspended`. All subsequent API calls from credentials in that tenant return `1000 UNAUTHORIZED`. In-flight transactions remain visible but cannot transition states.

```http theme={null}
POST /v1/tenants/{id}/suspend
```

```bash theme={null}
curl -X POST https://api.qustody.io/v1/tenants/tnt_01HXYZ/suspend \
  -H "Authorization: Bearer $QUSTODY_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "non-payment", "notify_email": "billing@acme.example"}'
```

## Reactivate tenant

Restores a suspended tenant to `active`. Webhook deliveries that accumulated during suspension are not replayed automatically — use [`/webhooks/{id}/replay`](/api-reference/admin/webhook-management#replay-a-delivery) if needed.

```http theme={null}
POST /v1/tenants/{id}/reactivate
```

```bash theme={null}
curl -X POST https://api.qustody.io/v1/tenants/tnt_01HXYZ/reactivate \
  -H "Authorization: Bearer $QUSTODY_ADMIN_KEY"
```

## Required permissions

| Endpoint                           | Permission       |
| ---------------------------------- | ---------------- |
| `PUT /v1/tenants/{id}`             | `tenants:update` |
| `POST /v1/tenants/{id}/suspend`    | `tenants:update` |
| `POST /v1/tenants/{id}/reactivate` | `tenants:update` |

Only `admin` has these by default.