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:

{
  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)
}

Tenant-level defaultPolicies are retired. Supplying that field returns HTTP 410 because the historical implementation was process-local and could diverge across replicas or disappear after restart. Configure durable policies for each agent through the Policies API. Response:

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

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.

Get Tenant

GET /tenants/:id

Auth: Tenant API key Response:

{
  "ok": true,
  "data": {
    "id": "my-org",
    "name": "My Organization"
  }
}

Retired Legacy Update

The historical update route remains only as an explicit fail-closed migration boundary. It performs no mutation and returns HTTP 410 for both webhookUrl and defaultPolicies payloads.

PUT /tenants/:id/webhook

Auth: Tenant owner/admin session with recent MFA Request Body:

{ defaultPolicies: PolicyRule[] }

Response:

{
  "ok": false,
  "error": "defaultPolicies are retired because process-local tenant policy state is not durable; use /policies and durable per-agent policy assignments instead"
}

Use /policies and the agent policy-assignment routes for durable policy authority. The SDK exposes those supported policy operations directly; it does not expose this retired legacy route. The generated OpenAPI contract likewise omits the retired route.

Webhook Migration and Events

Create signed webhook endpoints with POST /webhooks. The response returns the endpoint secret exactly once; store it in the receiver and use it to verify deliveries. Historical tenant webhookUrl values are inert and are not silently backfilled with an undisclosed random secret. When configured through /webhooks, Steward dispatches HTTP POST requests 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:

{
  "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.

Platform user provisioning, lookup, tenant user search, and wallet external ID assignment are documented separately in Platform Users.

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:

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

Delete Tenant

DELETE /platform/tenants/:id

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

Retired Tenant Default Policy Route

PUT /platform/tenants/:id/policies

This compatibility route returns HTTP 410 and performs no write. Tenant-wide process-local defaults are not policy authority. Use PUT /agents/:agentId/policies to persist the complete policy set for each agent instead.

Platform Stats

GET /platform/stats

Auth: Platform key Response:

{
  "ok": true,
  "data": {
    "tenants": 4,
    "agents": 17,
    "transactions": 70
  }
}

​Tenants API

​Create Tenant

​Get Tenant

​Retired Legacy Update

​Webhook Migration and Events

​Platform Tenant Management

​List All Tenants

​Get Tenant with Agent Count

​Create Tenant (Platform)

​Delete Tenant

​Retired Tenant Default Policy Route

​Platform Stats

Tenants API

Create Tenant

Get Tenant

Retired Legacy Update

Webhook Migration and Events

Platform Tenant Management

List All Tenants

Get Tenant with Agent Count

Create Tenant (Platform)

Delete Tenant

Retired Tenant Default Policy Route

Platform Stats