Skip to main content

​
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)
  webhookUrl?: string;      // URL for event webhooks
  defaultPolicies?: PolicyRule[];  // Default policies for new agents
}
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",
    "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: 
{
  webhookUrl?: string;          // Webhook URL (or null to remove)
  defaultPolicies?: PolicyRule[];  // Default policies for new agents
}
Response: 
{
  "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:
EventTrigger
approval_requiredTransaction queued for manual approval
tx_signedTransaction signed and (optionally) broadcast
tx_rejectedTransaction rejected by policy
tx_failedTransaction 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.

​
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.

​
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: 
{
  "ok": true,
  "data": {
    "tenants": 4,
    "agents": 17,
    "transactions": 70
  }
}