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

# Tenants

> Multi-tenant management — create organizations and configure settings.

# Tenants API

Tenants are the top-level isolation boundary in Steward. Each tenant has its own agents, secrets, policies, and API key.

## Create Tenant

```
POST /tenants
```

**Auth:** Varies (platform key for platform routes, or self-registration via SIWE)

**Request Body:**

```typescript theme={null}
{
  id: string;               // Unique tenant ID (1-64 alphanumeric, _ - . :)
  name: string;             // Display name
  apiKeyHash: string;       // SHA-256 hash of the API key (or raw key — Steward hashes it)
  webhookUrl?: string;      // URL for event webhooks
  defaultPolicies?: PolicyRule[];  // Default policies for new agents
}
```

**Response:**

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "my-org",
    "name": "My Organization",
    "apiKeyHash": "a1b2c3d4...",
    "createdAt": "2026-03-26T12:00:00Z"
  }
}
```

<Note>
  When creating via the platform API (`POST /platform/tenants`), the API key is auto-generated and returned once in the response. Store it securely — it cannot be retrieved again.
</Note>

***

## Get Tenant

```
GET /tenants/:id
```

**Auth:** Tenant API key

**Response:**

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "my-org",
    "name": "My Organization",
    "webhookUrl": "https://my-server.com/webhooks",
    "defaultPolicies": []
  }
}
```

***

## Update Webhook

Configure the webhook URL and default policies for a tenant.

```
PUT /tenants/:id/webhook
```

**Auth:** Tenant API key

**Request Body:**

```typescript theme={null}
{
  webhookUrl?: string;          // Webhook URL (or null to remove)
  defaultPolicies?: PolicyRule[];  // Default policies for new agents
}
```

**Response:**

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "my-org",
    "name": "My Organization",
    "webhookUrl": "https://my-server.com/webhooks",
    "defaultPolicies": [
      { "type": "spending-limit", "enabled": true, "config": { "maxPerDay": "1000000000000000000" } }
    ]
  }
}
```

### Webhook Events

When configured, Steward dispatches HTTP POST requests to your webhook URL for:

| Event               | Trigger                                       |
| ------------------- | --------------------------------------------- |
| `approval_required` | Transaction queued for manual approval        |
| `tx_signed`         | Transaction signed and (optionally) broadcast |
| `tx_rejected`       | Transaction rejected by policy                |
| `tx_failed`         | Transaction signing or broadcast failed       |

**Webhook payload:**

```json theme={null}
{
  "type": "tx_signed",
  "tenantId": "my-org",
  "agentId": "trading-agent",
  "data": {
    "txId": "550e8400-...",
    "txHash": "0x8d7592b..."
  },
  "timestamp": "2026-03-26T15:08:00Z"
}
```

***

## Platform Tenant Management

These endpoints are available via the platform API (`/platform/tenants`) and require a platform key.

<Note>
  Platform user provisioning, lookup, tenant user search, and wallet external ID
  assignment are documented separately in [Platform Users](/api-reference/platform-users).
</Note>

### List All Tenants

```
GET /platform/tenants
```

### Get Tenant with Agent Count

```
GET /platform/tenants/:id
```

Returns tenant details plus an `agentCount` field.

### Create Tenant (Platform)

```
POST /platform/tenants
```

Auto-generates an API key. The raw key is returned once:

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "new-org",
    "name": "New Organization",
    "apiKey": "stwd_a1b2c3d4...",
    "createdAt": "2026-03-26T12:00:00Z"
  }
}
```

### Delete Tenant

```
DELETE /platform/tenants/:id
```

<Warning>
  Deleting a tenant cascades to all agents, wallets, policies, and transactions. This is permanent.
</Warning>

### Set Default Policies

```
PUT /platform/tenants/:id/policies
```

Sets the default policy template for all agents in the tenant.

***

## Platform Stats

```
GET /platform/stats
```

**Auth:** Platform key

**Response:**

```json theme={null}
{
  "ok": true,
  "data": {
    "tenants": 4,
    "agents": 17,
    "transactions": 70
  }
}
```