{ "openapi": "3.1.0", "info": { "title": "Steward API", "version": "0.4.4", "description": "Generated OpenAPI contract for implemented Steward API surfaces. This contract includes Privy-parity account resources, wallet external IDs, gas spend filtering, transaction reference filtering, and request-hardening inventory markers for sensitive mutating routes." }, "servers": [ { "url": "http://localhost:3200", "description": "Your self-hosted Steward instance (Steward is self-host-first; replace with your deployment URL). The playground targets this rather than the docs domain." } ], "x-steward-sensitive-prefixes": [ "/vault", "/agents", "/v1/agents", "/wallets/batch", "/v1/wallets/batch", "/accounts", "/v1/accounts", "/adapters", "/v1/adapters", "/policies", "/v1/policies", "/secrets", "/trade", "/v1/trade", "/approvals", "/intents", "/audit", "/auth", "/global-wallet", "/user", "/v1/users", "/webhooks", "/tenants", "/platform", "/condition-sets", "/v1/condition-sets", "/condition_sets", "/v1/condition_sets", "/v2/workspaces", "/v2/provider-accounts", "/v2/provider-role-bindings", "/v2/provider-grants", "/v1/kms", "/v2/provider-actions", "/dashboard", "/agent-enroll", "/v1/agent-enroll" ], "tags": [ { "name": "Auth" }, { "name": "Digital Asset Accounts" }, { "name": "Platform Users" }, { "name": "Platform Tenants" }, { "name": "Platform Apps" }, { "name": "Tenant Users" }, { "name": "Policy Templates" }, { "name": "Condition Sets" }, { "name": "Wallets" }, { "name": "Vault" }, { "name": "Agent Authorization" }, { "name": "Intents" }, { "name": "Adapters" }, { "name": "Fiat" }, { "name": "Audits" }, { "name": "Secrets" }, { "name": "Webhooks" }, { "name": "Approvals" }, { "name": "Global Wallet" }, { "name": "Trading" }, { "name": "Tenant Config" }, { "name": "Provider Authority" } ], "components": { "securitySchemes": { "tenantApiKey": { "type": "apiKey", "in": "header", "name": "X-Steward-API-Key" }, "platformKey": { "type": "apiKey", "in": "header", "name": "X-Steward-Platform-Key" }, "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "TradeTokenStatus": { "type": "object", "required": [ "agentId", "status", "exp", "observedAt", "expiresInSeconds" ], "properties": { "agentId": { "type": "string" }, "status": { "type": "string", "enum": [ "unknown", "observed" ] }, "exp": { "type": [ "integer", "null" ] }, "observedAt": { "type": [ "string", "null" ] }, "expiresInSeconds": { "type": [ "integer", "null" ] } } } } }, "paths": { "/auth/mfa/totp/enroll": { "post": { "tags": [ "Auth" ], "summary": "Start TOTP MFA enrollment", "description": "Requires an authenticated user session and recent factor-enrollment step-up. Returns a one-time TOTP secret and otpauth URI for pending enrollment; clients must not persist the secret beyond setup.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "secret", "otpauthUri", "expiresAt" ], "properties": { "secret": { "type": "string" }, "otpauthUri": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/totp/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify TOTP code or complete pending TOTP enrollment", "description": "Requires an authenticated user session. MFA factor enrollment and unenrollment require recent step-up where configured, write audit events, and revoke refresh sessions after factor state changes. Pending enrollment verification returns one-time recovery codes and dispatches non-secret MFA/recovery webhooks.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "verified": { "type": "boolean" }, "recoveryCodes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/totp/complete": { "post": { "tags": [ "Auth" ], "summary": "Complete a TOTP MFA login challenge", "description": "Consumes exactly one pending TOTP MFA challenge using either a six-digit TOTP code or a recovery code. Consumes a pending MFA challenge atomically, rate-limits invalid attempts, re-checks active tenant membership before session issuance, and returns no-store session tokens only after verification.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challengeId" ], "properties": { "challengeId": { "type": "string" }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string" } }, "oneOf": [ { "required": [ "code" ] }, { "required": [ "recoveryCode" ] } ] } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "token", "refreshToken", "expiresIn" ], "properties": { "ok": { "type": "boolean", "const": true }, "token": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "integer", "minimum": 1 }, "user": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/totp/step-up": { "post": { "tags": [ "Auth" ], "summary": "Step up the current session with TOTP or a recovery code", "description": "Requires an authenticated user session and verifies either a six-digit TOTP code or one recovery code before issuing refreshed no-store session tokens with current MFA freshness claims.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string" } }, "oneOf": [ { "required": [ "code" ] }, { "required": [ "recoveryCode" ] } ] } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "token", "refreshToken", "expiresIn" ], "properties": { "ok": { "type": "boolean", "const": true }, "token": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "integer", "minimum": 1 }, "user": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/recovery-codes/regenerate": { "post": { "tags": [ "Auth" ], "summary": "Regenerate MFA recovery codes", "description": "Requires an authenticated user session plus a valid current TOTP code. Returns replacement recovery codes exactly once, writes audit events, and dispatches a non-secret recovery-setup webhook.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "recoveryCodes" ], "properties": { "recoveryCodes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/sms/enroll": { "post": { "tags": [ "Auth" ], "summary": "Start SMS MFA enrollment", "description": "Requires an authenticated user session. MFA factor enrollment and unenrollment require recent step-up where configured, write audit events, and revoke refresh sessions after factor state changes. Sends an OTP to an E.164 phone number and stores only pending masked-phone state.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "enabled": { "type": "boolean" }, "verified": { "type": "boolean" }, "phone": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "503": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/sms/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify pending SMS MFA enrollment", "description": "Requires an authenticated user session. MFA factor enrollment and unenrollment require recent step-up where configured, write audit events, and revoke refresh sessions after factor state changes. Enforces bounded failed-attempt counters, stores only the phone needed for MFA, and returns a masked phone value.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "enabled": { "type": "boolean" }, "verified": { "type": "boolean" }, "phone": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/sms/send": { "post": { "tags": [ "Auth" ], "summary": "Send an SMS MFA management OTP", "description": "Requires an authenticated user session with SMS MFA already enabled. Sends a bounded management OTP and returns only the masked phone and expiry.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "enabled": { "type": "boolean" }, "verified": { "type": "boolean" }, "phone": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "503": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/sms/complete": { "post": { "tags": [ "Auth" ], "summary": "Complete an SMS MFA login challenge", "description": "Consumes a pending MFA challenge atomically, rate-limits invalid attempts, re-checks active tenant membership before session issuance, and returns no-store session tokens only after verification.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challengeId", "code" ], "properties": { "challengeId": { "type": "string" }, "code": { "type": "string", "pattern": "^\\d{6}$" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "token", "refreshToken", "expiresIn" ], "properties": { "ok": { "type": "boolean", "const": true }, "token": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "integer", "minimum": 1 }, "user": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/sms/step-up": { "post": { "tags": [ "Auth" ], "summary": "Step up the current session with SMS MFA", "description": "Requires an authenticated user session plus an SMS management OTP from /auth/mfa/sms/send before issuing refreshed no-store session tokens with current MFA freshness claims.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "token", "refreshToken", "expiresIn" ], "properties": { "ok": { "type": "boolean", "const": true }, "token": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "integer", "minimum": 1 }, "user": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/sms/unenroll": { "post": { "tags": [ "Auth" ], "summary": "Unenroll SMS MFA", "description": "Requires an authenticated user session plus valid SMS management OTP. Writes audit events, dispatches mfa.disabled, and revokes refresh sessions after factor removal.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "enabled": { "type": "boolean", "const": false } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/passkey/options": { "post": { "tags": [ "Auth" ], "summary": "Create passkey MFA authentication options", "description": "Requires an authenticated user session, tenant passkey login-method allowlist, and a registered passkey. The returned challenge is stored server-side for one-time verification.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "challenge": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/passkey/complete": { "post": { "tags": [ "Auth" ], "summary": "Complete a passkey MFA step-up", "description": "Requires an authenticated user session and consumes a one-time WebAuthn challenge before issuing fresh no-store session tokens with recent-MFA claims.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challengeId", "response" ], "properties": { "challengeId": { "type": "string" }, "response": { "type": "object", "required": [ "id" ], "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "token", "refreshToken", "expiresIn" ], "properties": { "ok": { "type": "boolean", "const": true }, "token": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "integer", "minimum": 1 }, "user": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/mfa/passkey/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify a passkey MFA step-up", "description": "Alias for /auth/mfa/passkey/complete with the same one-time challenge rules.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challengeId", "response" ], "properties": { "challengeId": { "type": "string" }, "response": { "type": "object", "required": [ "id" ], "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "token", "refreshToken", "expiresIn" ], "properties": { "ok": { "type": "boolean", "const": true }, "token": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "integer", "minimum": 1 }, "user": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Log out and optionally revoke a refresh token", "description": "Idempotently revokes the presented access token JTI and optional refresh token, writes logout audit events when token context is available, and never returns session secrets.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": false } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Rotate a refresh token", "description": "Sensitive authentication session mutation. Responses that issue or rotate tokens are no-store; refresh tokens are single-use and reuse detection revokes the user's refresh-token family.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refreshToken" ], "properties": { "refreshToken": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "token", "refreshToken", "expiresIn" ], "properties": { "ok": { "type": "boolean", "const": true }, "token": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "integer", "minimum": 1 }, "user": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/auth/revoke": { "post": { "tags": [ "Auth" ], "summary": "Revoke a refresh token", "description": "Revokes a single refresh token by hash, writes audit events when the token exists, and remains idempotent for already-absent tokens.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refreshToken" ], "properties": { "refreshToken": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": false } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/auth", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/provider-actions": { "post": { "tags": [ "Provider Authority" ], "summary": "Invoke a governed provider action as an agent", "description": "Provider credentials are resolved server-side from the bound account and are never accepted in this request.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "workspaceId", "providerAccountId", "operationKey", "arguments", "idempotencyKey" ], "properties": { "workspaceId": { "type": "string" }, "providerAccountId": { "type": "string" }, "operationKey": { "type": "string" }, "arguments": { "type": "object", "additionalProperties": true }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 255 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "requestHash", "actionDigest" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_approval", "stub_succeeded", "stub_failed" ] }, "requestHash": { "type": "string" }, "actionDigest": { "type": "string" }, "result": { "type": "object", "additionalProperties": true } } } } } }, "202": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "requestHash", "actionDigest" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_approval", "stub_succeeded", "stub_failed" ] }, "requestHash": { "type": "string" }, "actionDigest": { "type": "string" }, "result": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "additionalProperties": false, "required": [ "ok", "error", "data" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" }, "data": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "requestHash", "actionDigest" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "denied_access", "denied_policy" ] }, "requestHash": { "type": "string" }, "actionDigest": { "type": "string" } } } } } ] } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/provider-actions", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/workspaces": { "get": { "tags": [ "Provider Authority" ], "summary": "List workspaces", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Provider Authority" ], "summary": "Create workspace", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expectedRevision", "reason" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "description": "Compare-and-set token: MUST equal the current tenant authority revision (provider_authority_tenant_state.revision). Read it from the authorityRevision field returned by GET /v2/workspaces (the only listing that surfaces it). Mismatch returns 409 revision_conflict." }, "reason": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/workspaces", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/workspaces/{id}/disable": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Provider Authority" ], "summary": "Disable workspace", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expectedRevision", "reason" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "description": "Compare-and-set token: MUST equal this object's own current revision. Mismatch returns 409 revision_conflict." }, "reason": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/workspaces", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/provider-accounts": { "get": { "tags": [ "Provider Authority" ], "summary": "List provider accounts", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Provider Authority" ], "summary": "Create provider account", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expectedRevision", "reason" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "description": "Compare-and-set token: MUST equal the parent workspace's current revision. Mismatch returns 409 revision_conflict." }, "reason": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/provider-accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/provider-accounts/{id}/disable": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Provider Authority" ], "summary": "Disable provider account", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expectedRevision", "reason" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "description": "Compare-and-set token: MUST equal this object's own current revision. Mismatch returns 409 revision_conflict." }, "reason": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/provider-accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/provider-accounts/{id}/operations": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Provider Authority" ], "summary": "List provider operations", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Provider Authority" ], "summary": "Register provider operation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expectedRevision", "reason" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "description": "Compare-and-set token: MUST equal the parent provider account's current revision. Mismatch returns 409 revision_conflict." }, "reason": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/provider-accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/provider-role-bindings": { "get": { "tags": [ "Provider Authority" ], "summary": "List provider role bindings", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Provider Authority" ], "summary": "Issue provider role binding", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expectedRevision", "reason" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "description": "Compare-and-set token whose binding target depends on role_key: for role_key='tenant_authority_admin' it MUST equal the tenant authority revision (provider_authority_tenant_state.revision, from the authorityRevision field of GET /v2/workspaces); for every workspace-scoped role (workspace_admin/operator/viewer/approver) it MUST equal the target workspace's current revision. Mismatch returns 409 revision_conflict." }, "reason": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/provider-role-bindings", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/provider-role-bindings/{id}/revoke": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Provider Authority" ], "summary": "Revoke provider role binding", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expectedRevision", "reason" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "description": "Compare-and-set token: MUST equal this object's own current revision. Mismatch returns 409 revision_conflict." }, "reason": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/provider-role-bindings", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/provider-grants": { "get": { "tags": [ "Provider Authority" ], "summary": "List direct provider grants", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Provider Authority" ], "summary": "Issue non-delegable provider grant", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expectedRevision", "reason" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "description": "Compare-and-set token: MUST equal the parent workspace's current revision. Mismatch returns 409 revision_conflict." }, "reason": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/provider-grants", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/provider-grants/{id}/revoke": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Provider Authority" ], "summary": "Revoke provider grant", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expectedRevision", "reason" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "description": "Compare-and-set token: MUST equal this object's own current revision. Mismatch returns 409 revision_conflict." }, "reason": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/provider-grants", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/provider-access/check": { "post": { "tags": [ "Provider Authority" ], "summary": "Evaluate structural provider access without execution policy", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v2/provider-actions/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Provider Authority" ], "summary": "Get the authenticated agent's own provider-action status", "description": "Requires an agent JWT. The action is scoped server-side to the verified tenant and agent; absent, malformed, cross-agent, and cross-tenant ids all return the same 404 response. This route does not grant access to the human/MFA-gated approval, case, or evidence surfaces.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Steward-Tenant", "in": "header", "required": false, "description": "Tenant containing the authenticated agent. It is checked against the verified agent principal and never selects a foreign action.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "version", "workspaceId", "providerAccountId", "operationId", "operationRevision", "actionDigest", "requestHash", "expiresAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "denied", "pending_approval", "allowed_stub", "stub_succeeded", "stub_failed", "approved", "execution_ready", "approval_denied", "approval_expired", "approval_stale", "executing", "succeeded", "failed", "outcome_unknown" ] }, "version": { "type": "integer", "minimum": 1 }, "workspaceId": { "type": "string" }, "providerAccountId": { "type": "string" }, "operationId": { "type": "string" }, "operationRevision": { "type": "integer", "minimum": 1 }, "actionDigest": { "type": "string" }, "requestHash": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v2/provider-actions/{id}/approval": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Provider Authority" ], "summary": "Get exact-request approval detail", "description": "Requires an eligible human session with recent MFA.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "status", "version", "requestHash", "actionDigest", "expiresAt", "safeSummary", "operationId", "providerAccountId", "workspaceId" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "denied", "pending_approval", "allowed_stub", "stub_succeeded", "stub_failed", "approved", "execution_ready", "approval_denied", "approval_expired", "approval_stale", "executing", "succeeded", "failed", "outcome_unknown" ] }, "version": { "type": "integer" }, "requestHash": { "type": "string" }, "actionDigest": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "safeSummary": { "type": [ "object", "null" ], "additionalProperties": true }, "operationId": { "type": "string" }, "providerAccountId": { "type": "string" }, "workspaceId": { "type": "string" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Provider Authority" ], "summary": "Approve or deny an exact provider request", "description": "Requires an eligible human session with recent MFA.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "decision", "expectedVersion", "expectedRequestHash", "expectedActionDigest", "idempotencyKey" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "deny" ] }, "expectedVersion": { "type": "integer" }, "expectedRequestHash": { "type": "string" }, "expectedActionDigest": { "type": "string" }, "reasonCode": { "type": "string", "enum": [ "approver_manual_approve", "approver_manual_deny", "approver_risk_deny", "approver_scope_deny", "approver_duplicate_deny", "approver_other" ] }, "reason": { "type": "string", "maxLength": 1000 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 255 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "version", "requestHash", "actionDigest" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "denied", "pending_approval", "allowed_stub", "stub_succeeded", "stub_failed", "approved", "execution_ready", "approval_denied", "approval_expired", "approval_stale", "executing", "succeeded", "failed", "outcome_unknown" ] }, "version": { "type": "integer" }, "requestHash": { "type": "string" }, "actionDigest": { "type": "string" }, "replayed": { "type": "boolean" }, "resumeAttemptId": { "type": "string" } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/provider-actions", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/provider-actions/{id}/execute": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Provider Authority" ], "summary": "Request safe resume of an approved provider action", "description": "The server authorizes the caller against persisted ownership and exact approval state. Resume is state-idempotent through the binding and execution nonce; this endpoint accepts no request body.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "version", "requestHash", "actionDigest" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "denied", "pending_approval", "allowed_stub", "stub_succeeded", "stub_failed", "approved", "execution_ready", "approval_denied", "approval_expired", "approval_stale", "executing", "succeeded", "failed", "outcome_unknown" ] }, "version": { "type": "integer" }, "requestHash": { "type": "string" }, "actionDigest": { "type": "string" }, "replayed": { "type": "boolean" }, "resumeAttemptId": { "type": "string" } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v2/provider-actions", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v2/provider-actions/{id}/case": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Provider Authority" ], "summary": "Get a provider-action case manifest", "description": "Requires an owner/admin human session with recent MFA.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "caseId", "tenantId", "workspaceId", "requestActor", "approvalActor", "resumeActor", "providerAccount", "operation", "actionDigest", "requestHash", "idempotencyKeyHash", "accessDecision", "policyDecision", "approvalCommitmentHash", "execution", "dependencyRevisions", "events", "eventSeqRange", "terminalState", "completeness", "missingRequiredRoles", "incompletenessReasons", "safeSummary", "genesisAt", "terminalAt", "assembledAt" ], "properties": { "schemaVersion": { "type": "string", "const": "steward.provider-case-manifest.v1" }, "caseId": { "type": "string" }, "tenantId": { "type": "string" }, "workspaceId": { "type": "string" }, "requestActor": { "type": "object", "additionalProperties": false, "required": [ "type", "id", "revision" ], "properties": { "type": { "type": "string", "const": "agent" }, "id": { "type": "string" }, "revision": { "type": "integer" } } }, "approvalActor": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "type", "id" ], "properties": { "type": { "type": "string", "const": "user" }, "id": { "type": "string" } } } ] }, "resumeActor": { "type": [ "string", "null" ], "enum": [ "steward-system", null ] }, "providerAccount": { "type": "object", "additionalProperties": false, "required": [ "id", "revision" ], "properties": { "id": { "type": "string" }, "revision": { "type": "integer" } } }, "operation": { "type": "object", "additionalProperties": false, "required": [ "id", "key", "revision", "canonicalProfile", "riskClass" ], "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "revision": { "type": "integer" }, "canonicalProfile": { "type": "string" }, "riskClass": { "type": "string" } } }, "actionDigest": { "type": "string" }, "requestHash": { "type": "string" }, "idempotencyKeyHash": { "type": "string" }, "accessDecision": { "type": "object", "additionalProperties": false, "required": [ "id", "hash", "effect" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "effect": { "type": "string", "enum": [ "allow", "deny" ] } } }, "policyDecision": { "type": "object", "additionalProperties": false, "required": [ "id", "hash", "effect" ], "properties": { "id": { "type": [ "string", "null" ] }, "hash": { "type": [ "string", "null" ] }, "effect": { "type": "string" } } }, "approvalCommitmentHash": { "type": [ "string", "null" ] }, "execution": { "type": [ "object", "null" ], "additionalProperties": true }, "dependencyRevisions": { "type": "object", "additionalProperties": true }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "seq", "action", "role", "hmac" ], "properties": { "seq": { "type": "integer" }, "action": { "type": "string" }, "role": { "type": "string" }, "hmac": { "type": "string" } } } }, "eventSeqRange": { "type": [ "object", "null" ], "additionalProperties": true }, "terminalState": { "type": "string" }, "completeness": { "type": "string", "enum": [ "complete", "incomplete", "unknown" ] }, "missingRequiredRoles": { "type": "array", "items": { "type": "string" } }, "incompletenessReasons": { "type": "array", "items": { "type": "string" } }, "safeSummary": { "type": [ "object", "null" ], "additionalProperties": true }, "genesisAt": { "type": [ "string", "null" ], "format": "date-time" }, "terminalAt": { "type": [ "string", "null" ], "format": "date-time" }, "assembledAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v2/provider-actions/{id}/evidence": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Provider Authority" ], "summary": "Get signed provider-action case evidence", "description": "Requires an owner/admin human session with recent MFA.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "version", "tenantId", "caseId", "manifest", "bundle", "completeness", "generatedAt" ], "properties": { "version": { "type": "integer", "const": 1 }, "tenantId": { "type": "string" }, "caseId": { "type": "string" }, "manifest": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "caseId", "tenantId", "workspaceId", "requestActor", "approvalActor", "resumeActor", "providerAccount", "operation", "actionDigest", "requestHash", "idempotencyKeyHash", "accessDecision", "policyDecision", "approvalCommitmentHash", "execution", "dependencyRevisions", "events", "eventSeqRange", "terminalState", "completeness", "missingRequiredRoles", "incompletenessReasons", "safeSummary", "genesisAt", "terminalAt", "assembledAt" ], "properties": { "schemaVersion": { "type": "string", "const": "steward.provider-case-manifest.v1" }, "caseId": { "type": "string" }, "tenantId": { "type": "string" }, "workspaceId": { "type": "string" }, "requestActor": { "type": "object", "additionalProperties": false, "required": [ "type", "id", "revision" ], "properties": { "type": { "type": "string", "const": "agent" }, "id": { "type": "string" }, "revision": { "type": "integer" } } }, "approvalActor": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "type", "id" ], "properties": { "type": { "type": "string", "const": "user" }, "id": { "type": "string" } } } ] }, "resumeActor": { "type": [ "string", "null" ], "enum": [ "steward-system", null ] }, "providerAccount": { "type": "object", "additionalProperties": false, "required": [ "id", "revision" ], "properties": { "id": { "type": "string" }, "revision": { "type": "integer" } } }, "operation": { "type": "object", "additionalProperties": false, "required": [ "id", "key", "revision", "canonicalProfile", "riskClass" ], "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "revision": { "type": "integer" }, "canonicalProfile": { "type": "string" }, "riskClass": { "type": "string" } } }, "actionDigest": { "type": "string" }, "requestHash": { "type": "string" }, "idempotencyKeyHash": { "type": "string" }, "accessDecision": { "type": "object", "additionalProperties": false, "required": [ "id", "hash", "effect" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "effect": { "type": "string", "enum": [ "allow", "deny" ] } } }, "policyDecision": { "type": "object", "additionalProperties": false, "required": [ "id", "hash", "effect" ], "properties": { "id": { "type": [ "string", "null" ] }, "hash": { "type": [ "string", "null" ] }, "effect": { "type": "string" } } }, "approvalCommitmentHash": { "type": [ "string", "null" ] }, "execution": { "type": [ "object", "null" ], "additionalProperties": true }, "dependencyRevisions": { "type": "object", "additionalProperties": true }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "seq", "action", "role", "hmac" ], "properties": { "seq": { "type": "integer" }, "action": { "type": "string" }, "role": { "type": "string" }, "hmac": { "type": "string" } } } }, "eventSeqRange": { "type": [ "object", "null" ], "additionalProperties": true }, "terminalState": { "type": "string" }, "completeness": { "type": "string", "enum": [ "complete", "incomplete", "unknown" ] }, "missingRequiredRoles": { "type": "array", "items": { "type": "string" } }, "incompletenessReasons": { "type": "array", "items": { "type": "string" } }, "safeSummary": { "type": [ "object", "null" ], "additionalProperties": true }, "genesisAt": { "type": [ "string", "null" ], "format": "date-time" }, "terminalAt": { "type": [ "string", "null" ], "format": "date-time" }, "assembledAt": { "type": "string", "format": "date-time" } } }, "bundle": { "type": "object", "additionalProperties": true }, "completeness": { "type": "string", "enum": [ "complete", "incomplete", "unknown" ] }, "generatedAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/accounts": { "get": { "tags": [ "Digital Asset Accounts" ], "summary": "List digital asset accounts", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "displayName", "metadata", "walletIds", "wallets", "capabilities", "capabilityMetadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "owner_user_ids": { "type": "array", "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "items": { "type": "string" } }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "wallets": { "type": "array", "items": { "type": "object", "required": [ "id", "walletId", "membershipId", "name", "chainType", "chainFamily", "address", "capabilities", "capabilityMetadata" ], "properties": { "id": { "type": "string" }, "walletId": { "type": "string" }, "membershipId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] }, "walletType": { "type": [ "string", "null" ] }, "wallet_type": { "type": [ "string", "null" ] }, "custody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "user_embedded" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] } } }, "signing": { "type": "object", "properties": { "signerCount": { "type": "integer", "minimum": 0 }, "activeSignerCount": { "type": "integer", "minimum": 0 }, "quorumCount": { "type": "integer", "minimum": 0 }, "activeQuorumCount": { "type": "integer", "minimum": 0 } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "chainType": { "type": "string", "enum": [ "ethereum", "solana", "bitcoin", "monero" ] }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "address": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Digital Asset Accounts" ], "summary": "Create a digital asset account", "security": [ { "tenantApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "owner_user_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "ownerUserIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "wallet_ids": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "walletIds": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "user_wallet_ids": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "userWalletIds": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "wallets_configuration": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "chain_type": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "chainType": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "name": { "type": "string" }, "wallet_id": { "type": "string" }, "walletId": { "type": "string" } } } }, "walletsConfiguration": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "chainType": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "name": { "type": "string" }, "walletId": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "displayName", "metadata", "walletIds", "wallets", "capabilities", "capabilityMetadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "owner_user_ids": { "type": "array", "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "items": { "type": "string" } }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "wallets": { "type": "array", "items": { "type": "object", "required": [ "id", "walletId", "membershipId", "name", "chainType", "chainFamily", "address", "capabilities", "capabilityMetadata" ], "properties": { "id": { "type": "string" }, "walletId": { "type": "string" }, "membershipId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] }, "walletType": { "type": [ "string", "null" ] }, "wallet_type": { "type": [ "string", "null" ] }, "custody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "user_embedded" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] } } }, "signing": { "type": "object", "properties": { "signerCount": { "type": "integer", "minimum": 0 }, "activeSignerCount": { "type": "integer", "minimum": 0 }, "quorumCount": { "type": "integer", "minimum": 0 }, "activeQuorumCount": { "type": "integer", "minimum": 0 } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "chainType": { "type": "string", "enum": [ "ethereum", "solana", "bitcoin", "monero" ] }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "address": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/accounts/{accountId}": { "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Digital Asset Accounts" ], "summary": "Get a digital asset account", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "displayName", "metadata", "walletIds", "wallets", "capabilities", "capabilityMetadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "owner_user_ids": { "type": "array", "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "items": { "type": "string" } }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "wallets": { "type": "array", "items": { "type": "object", "required": [ "id", "walletId", "membershipId", "name", "chainType", "chainFamily", "address", "capabilities", "capabilityMetadata" ], "properties": { "id": { "type": "string" }, "walletId": { "type": "string" }, "membershipId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] }, "walletType": { "type": [ "string", "null" ] }, "wallet_type": { "type": [ "string", "null" ] }, "custody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "user_embedded" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] } } }, "signing": { "type": "object", "properties": { "signerCount": { "type": "integer", "minimum": 0 }, "activeSignerCount": { "type": "integer", "minimum": 0 }, "quorumCount": { "type": "integer", "minimum": 0 }, "activeQuorumCount": { "type": "integer", "minimum": 0 } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "chainType": { "type": "string", "enum": [ "ethereum", "solana", "bitcoin", "monero" ] }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "address": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "patch": { "tags": [ "Digital Asset Accounts" ], "summary": "Update a digital asset account", "security": [ { "tenantApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "owner_user_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "ownerUserIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "wallet_ids": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "walletIds": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "user_wallet_ids": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "userWalletIds": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "wallets_configuration": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "chain_type": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "chainType": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "name": { "type": "string" }, "wallet_id": { "type": "string" }, "walletId": { "type": "string" } } } }, "walletsConfiguration": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "chainType": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "name": { "type": "string" }, "walletId": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "displayName", "metadata", "walletIds", "wallets", "capabilities", "capabilityMetadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "owner_user_ids": { "type": "array", "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "items": { "type": "string" } }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "wallets": { "type": "array", "items": { "type": "object", "required": [ "id", "walletId", "membershipId", "name", "chainType", "chainFamily", "address", "capabilities", "capabilityMetadata" ], "properties": { "id": { "type": "string" }, "walletId": { "type": "string" }, "membershipId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] }, "walletType": { "type": [ "string", "null" ] }, "wallet_type": { "type": [ "string", "null" ] }, "custody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "user_embedded" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] } } }, "signing": { "type": "object", "properties": { "signerCount": { "type": "integer", "minimum": 0 }, "activeSignerCount": { "type": "integer", "minimum": 0 }, "quorumCount": { "type": "integer", "minimum": 0 }, "activeQuorumCount": { "type": "integer", "minimum": 0 } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "chainType": { "type": "string", "enum": [ "ethereum", "solana", "bitcoin", "monero" ] }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "address": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Digital Asset Accounts" ], "summary": "Delete a digital asset account", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/accounts/{accountId}/balance": { "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "tokens", "in": "query", "required": false, "schema": { "type": "string" } } ], "get": { "tags": [ "Digital Asset Accounts" ], "summary": "Get grouped wallet membership and native/token balance rollups for an account", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "account_id": { "type": "string" }, "wallets": { "type": "array", "items": { "type": "object", "required": [ "id", "walletId", "membershipId", "name", "chainType", "chainFamily", "address", "capabilities", "capabilityMetadata" ], "properties": { "id": { "type": "string" }, "walletId": { "type": "string" }, "membershipId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] }, "walletType": { "type": [ "string", "null" ] }, "wallet_type": { "type": [ "string", "null" ] }, "custody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "user_embedded" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] } } }, "signing": { "type": "object", "properties": { "signerCount": { "type": "integer", "minimum": 0 }, "activeSignerCount": { "type": "integer", "minimum": 0 }, "quorumCount": { "type": "integer", "minimum": 0 }, "activeQuorumCount": { "type": "integer", "minimum": 0 } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "chainType": { "type": "string", "enum": [ "ethereum", "solana", "bitcoin", "monero" ] }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "address": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "balances": { "type": "array", "items": { "type": "object", "required": [ "walletId", "chainFamily", "chainId", "symbol", "native", "nativeFormatted", "walletAddress" ], "properties": { "walletId": { "type": "string" }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "chainId": { "type": [ "integer", "null" ] }, "symbol": { "type": [ "string", "null" ] }, "native": { "type": [ "string", "null" ] }, "nativeFormatted": { "type": [ "string", "null" ] }, "walletAddress": { "type": [ "string", "null" ] }, "unavailableReason": { "type": "string" } } } }, "tokenBalances": { "type": "array", "items": { "type": "object", "required": [ "walletId", "chainId", "token", "symbol", "balance", "formatted", "decimals" ], "properties": { "walletId": { "type": "string" }, "chainId": { "type": "integer" }, "token": { "type": "string" }, "symbol": { "type": "string" }, "balance": { "type": "string" }, "formatted": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0 }, "unavailableReason": { "type": "string" } } } }, "rollups": { "type": "object", "properties": { "native": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "symbol": { "type": "string" }, "native": { "type": "string" } } } }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "token": { "type": "string" }, "symbol": { "type": "string" }, "balance": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0 } } } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/accounts/{accountId}/aggregations": { "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Digital Asset Accounts" ], "summary": "List account aggregation snapshots", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "aggregations": { "type": "array", "items": { "type": "object", "required": [ "id", "accountId", "tenantId", "displayName", "walletIds", "chainFamilies", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "account_id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "chainFamilies": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "chain_families": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Digital Asset Accounts" ], "summary": "Create an account aggregation snapshot", "security": [ { "tenantApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "accountId", "tenantId", "displayName", "walletIds", "chainFamilies", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "account_id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "chainFamilies": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "chain_families": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/accounts/{accountId}/aggregations/{aggregationId}": { "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aggregationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Digital Asset Accounts" ], "summary": "Get an account aggregation snapshot", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "accountId", "tenantId", "displayName", "walletIds", "chainFamilies", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "account_id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "chainFamilies": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "chain_families": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "delete": { "tags": [ "Digital Asset Accounts" ], "summary": "Delete an account aggregation snapshot", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/accounts": { "get": { "tags": [ "Digital Asset Accounts" ], "summary": "List digital asset accounts", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "displayName", "metadata", "walletIds", "wallets", "capabilities", "capabilityMetadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "owner_user_ids": { "type": "array", "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "items": { "type": "string" } }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "wallets": { "type": "array", "items": { "type": "object", "required": [ "id", "walletId", "membershipId", "name", "chainType", "chainFamily", "address", "capabilities", "capabilityMetadata" ], "properties": { "id": { "type": "string" }, "walletId": { "type": "string" }, "membershipId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] }, "walletType": { "type": [ "string", "null" ] }, "wallet_type": { "type": [ "string", "null" ] }, "custody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "user_embedded" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] } } }, "signing": { "type": "object", "properties": { "signerCount": { "type": "integer", "minimum": 0 }, "activeSignerCount": { "type": "integer", "minimum": 0 }, "quorumCount": { "type": "integer", "minimum": 0 }, "activeQuorumCount": { "type": "integer", "minimum": 0 } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "chainType": { "type": "string", "enum": [ "ethereum", "solana", "bitcoin", "monero" ] }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "address": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Digital Asset Accounts" ], "summary": "Create a digital asset account", "security": [ { "tenantApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "owner_user_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "ownerUserIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "wallet_ids": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "walletIds": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "user_wallet_ids": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "userWalletIds": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "wallets_configuration": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "chain_type": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "chainType": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "name": { "type": "string" }, "wallet_id": { "type": "string" }, "walletId": { "type": "string" } } } }, "walletsConfiguration": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "chainType": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "name": { "type": "string" }, "walletId": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "displayName", "metadata", "walletIds", "wallets", "capabilities", "capabilityMetadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "owner_user_ids": { "type": "array", "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "items": { "type": "string" } }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "wallets": { "type": "array", "items": { "type": "object", "required": [ "id", "walletId", "membershipId", "name", "chainType", "chainFamily", "address", "capabilities", "capabilityMetadata" ], "properties": { "id": { "type": "string" }, "walletId": { "type": "string" }, "membershipId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] }, "walletType": { "type": [ "string", "null" ] }, "wallet_type": { "type": [ "string", "null" ] }, "custody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "user_embedded" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] } } }, "signing": { "type": "object", "properties": { "signerCount": { "type": "integer", "minimum": 0 }, "activeSignerCount": { "type": "integer", "minimum": 0 }, "quorumCount": { "type": "integer", "minimum": 0 }, "activeQuorumCount": { "type": "integer", "minimum": 0 } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "chainType": { "type": "string", "enum": [ "ethereum", "solana", "bitcoin", "monero" ] }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "address": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/accounts/{accountId}": { "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Digital Asset Accounts" ], "summary": "Get a digital asset account", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "displayName", "metadata", "walletIds", "wallets", "capabilities", "capabilityMetadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "owner_user_ids": { "type": "array", "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "items": { "type": "string" } }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "wallets": { "type": "array", "items": { "type": "object", "required": [ "id", "walletId", "membershipId", "name", "chainType", "chainFamily", "address", "capabilities", "capabilityMetadata" ], "properties": { "id": { "type": "string" }, "walletId": { "type": "string" }, "membershipId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] }, "walletType": { "type": [ "string", "null" ] }, "wallet_type": { "type": [ "string", "null" ] }, "custody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "user_embedded" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] } } }, "signing": { "type": "object", "properties": { "signerCount": { "type": "integer", "minimum": 0 }, "activeSignerCount": { "type": "integer", "minimum": 0 }, "quorumCount": { "type": "integer", "minimum": 0 }, "activeQuorumCount": { "type": "integer", "minimum": 0 } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "chainType": { "type": "string", "enum": [ "ethereum", "solana", "bitcoin", "monero" ] }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "address": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "patch": { "tags": [ "Digital Asset Accounts" ], "summary": "Update a digital asset account", "security": [ { "tenantApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "owner_user_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "ownerUserIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "wallet_ids": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "walletIds": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "user_wallet_ids": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "userWalletIds": { "type": "array", "maxItems": 5, "items": { "type": "string" } }, "wallets_configuration": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "chain_type": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "chainType": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "name": { "type": "string" }, "wallet_id": { "type": "string" }, "walletId": { "type": "string" } } } }, "walletsConfiguration": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "chainType": { "type": "string", "enum": [ "ethereum", "evm", "solana", "bitcoin", "monero" ] }, "name": { "type": "string" }, "walletId": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "displayName", "metadata", "walletIds", "wallets", "capabilities", "capabilityMetadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "ownerUserIds": { "type": "array", "items": { "type": "string" } }, "owner_user_ids": { "type": "array", "items": { "type": "string" } }, "additionalSignerIds": { "type": "array", "items": { "type": "string" } }, "additional_signer_ids": { "type": "array", "items": { "type": "string" } }, "signerPolicyIds": { "type": "array", "items": { "type": "string" } }, "signer_policy_ids": { "type": "array", "items": { "type": "string" } }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "wallets": { "type": "array", "items": { "type": "object", "required": [ "id", "walletId", "membershipId", "name", "chainType", "chainFamily", "address", "capabilities", "capabilityMetadata" ], "properties": { "id": { "type": "string" }, "walletId": { "type": "string" }, "membershipId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] }, "walletType": { "type": [ "string", "null" ] }, "wallet_type": { "type": [ "string", "null" ] }, "custody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "user_embedded" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] } } }, "signing": { "type": "object", "properties": { "signerCount": { "type": "integer", "minimum": 0 }, "activeSignerCount": { "type": "integer", "minimum": 0 }, "quorumCount": { "type": "integer", "minimum": 0 }, "activeQuorumCount": { "type": "integer", "minimum": 0 } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "chainType": { "type": "string", "enum": [ "ethereum", "solana", "bitcoin", "monero" ] }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "address": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Digital Asset Accounts" ], "summary": "Delete a digital asset account", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/accounts/{accountId}/balance": { "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "tokens", "in": "query", "required": false, "schema": { "type": "string" } } ], "get": { "tags": [ "Digital Asset Accounts" ], "summary": "Get grouped wallet membership and native/token balance rollups for an account", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "account_id": { "type": "string" }, "wallets": { "type": "array", "items": { "type": "object", "required": [ "id", "walletId", "membershipId", "name", "chainType", "chainFamily", "address", "capabilities", "capabilityMetadata" ], "properties": { "id": { "type": "string" }, "walletId": { "type": "string" }, "membershipId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] }, "walletType": { "type": [ "string", "null" ] }, "wallet_type": { "type": [ "string", "null" ] }, "custody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "user_embedded" ] }, "ownerUserId": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "string", "null" ] } } }, "signing": { "type": "object", "properties": { "signerCount": { "type": "integer", "minimum": 0 }, "activeSignerCount": { "type": "integer", "minimum": 0 }, "quorumCount": { "type": "integer", "minimum": 0 }, "activeQuorumCount": { "type": "integer", "minimum": 0 } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "chainType": { "type": "string", "enum": [ "ethereum", "solana", "bitcoin", "monero" ] }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "address": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sign_transaction", "sign_message", "sign_typed_data", "sign_user_operation", "sign_authorization", "send_calls", "transfer", "solana_transaction", "export_private_key" ] } }, "capabilityMetadata": { "type": "object", "additionalProperties": true }, "capability_metadata": { "type": "object", "additionalProperties": true }, "balances": { "type": "array", "items": { "type": "object", "required": [ "walletId", "chainFamily", "chainId", "symbol", "native", "nativeFormatted", "walletAddress" ], "properties": { "walletId": { "type": "string" }, "chainFamily": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "monero" ] }, "chainId": { "type": [ "integer", "null" ] }, "symbol": { "type": [ "string", "null" ] }, "native": { "type": [ "string", "null" ] }, "nativeFormatted": { "type": [ "string", "null" ] }, "walletAddress": { "type": [ "string", "null" ] }, "unavailableReason": { "type": "string" } } } }, "tokenBalances": { "type": "array", "items": { "type": "object", "required": [ "walletId", "chainId", "token", "symbol", "balance", "formatted", "decimals" ], "properties": { "walletId": { "type": "string" }, "chainId": { "type": "integer" }, "token": { "type": "string" }, "symbol": { "type": "string" }, "balance": { "type": "string" }, "formatted": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0 }, "unavailableReason": { "type": "string" } } } }, "rollups": { "type": "object", "properties": { "native": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "symbol": { "type": "string" }, "native": { "type": "string" } } } }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "token": { "type": "string" }, "symbol": { "type": "string" }, "balance": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0 } } } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/accounts/{accountId}/aggregations": { "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Digital Asset Accounts" ], "summary": "List account aggregation snapshots", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "aggregations": { "type": "array", "items": { "type": "object", "required": [ "id", "accountId", "tenantId", "displayName", "walletIds", "chainFamilies", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "account_id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "chainFamilies": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "chain_families": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Digital Asset Accounts" ], "summary": "Create an account aggregation snapshot", "security": [ { "tenantApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "accountId", "tenantId", "displayName", "walletIds", "chainFamilies", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "account_id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "chainFamilies": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "chain_families": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/accounts/{accountId}/aggregations/{aggregationId}": { "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aggregationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Digital Asset Accounts" ], "summary": "Get an account aggregation snapshot", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "accountId", "tenantId", "displayName", "walletIds", "chainFamilies", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "account_id": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "walletIds": { "type": "array", "items": { "type": "string" } }, "wallet_ids": { "type": "array", "items": { "type": "string" } }, "chainFamilies": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "chain_families": { "type": "array", "items": { "type": "string", "enum": [ "evm", "solana" ] } }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "delete": { "tags": [ "Digital Asset Accounts" ], "summary": "Delete an account aggregation snapshot", "security": [ { "tenantApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/accounts", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/policies": { "get": { "tags": [ "Policy Templates" ], "summary": "List policy templates", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "name", "description", "rules", "isDefault", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Policy Templates" ], "summary": "Create a policy template", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" } }, "required": [ "name", "rules" ] } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "rules", "isDefault", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/policies", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/policies/simulate": { "post": { "tags": [ "Policy Templates" ], "summary": "Simulate policy evaluation", "security": [ { "bearerAuth": [] }, { "tenantApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policyId": { "type": "string" }, "agentId": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "request": { "anyOf": [ { "type": "object", "required": [ "to", "value" ], "properties": { "kind": { "type": "string", "const": "transaction" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 } } }, { "type": "object", "required": [ "method", "url" ], "properties": { "kind": { "type": "string", "const": "proxy" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "url": { "type": "string" }, "body": {}, "data": {}, "value": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 } } } ] }, "kind": { "type": "string", "enum": [ "transaction", "proxy" ] }, "to": { "type": "string" }, "value": { "type": "string" }, "data": {}, "chainId": { "type": "integer", "minimum": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "url": { "type": "string" }, "body": {} } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "approved", "requiresManualApproval", "results", "counters" ], "properties": { "approved": { "type": "boolean" }, "requiresManualApproval": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "counters": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/policies", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/policies/{templateId}": { "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Policy Templates" ], "summary": "Get a policy template", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "rules", "isDefault", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "put": { "tags": [ "Policy Templates" ], "summary": "Update a policy template", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "rules", "isDefault", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/policies", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Policy Templates" ], "summary": "Delete a policy template", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/policies", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/policies/{templateId}/assign": { "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Policy Templates" ], "summary": "Assign a policy template to agents", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentIds" ], "properties": { "agentIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "templateId", "assignedAgents", "rulesApplied" ], "properties": { "templateId": { "type": "string" }, "assignedAgents": { "type": "array", "items": { "type": "string" } }, "rulesApplied": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/policies", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/policies": { "get": { "tags": [ "Policy Templates" ], "summary": "List policy templates", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "name", "description", "rules", "isDefault", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Policy Templates" ], "summary": "Create a policy template", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" } }, "required": [ "name", "rules" ] } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "rules", "isDefault", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/policies", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/policies/simulate": { "post": { "tags": [ "Policy Templates" ], "summary": "Simulate policy evaluation", "security": [ { "bearerAuth": [] }, { "tenantApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policyId": { "type": "string" }, "agentId": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "request": { "anyOf": [ { "type": "object", "required": [ "to", "value" ], "properties": { "kind": { "type": "string", "const": "transaction" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 } } }, { "type": "object", "required": [ "method", "url" ], "properties": { "kind": { "type": "string", "const": "proxy" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "url": { "type": "string" }, "body": {}, "data": {}, "value": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 } } } ] }, "kind": { "type": "string", "enum": [ "transaction", "proxy" ] }, "to": { "type": "string" }, "value": { "type": "string" }, "data": {}, "chainId": { "type": "integer", "minimum": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "url": { "type": "string" }, "body": {} } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "approved", "requiresManualApproval", "results", "counters" ], "properties": { "approved": { "type": "boolean" }, "requiresManualApproval": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "counters": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/policies", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/policies/{templateId}": { "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Policy Templates" ], "summary": "Get a policy template", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "rules", "isDefault", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "put": { "tags": [ "Policy Templates" ], "summary": "Update a policy template", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "rules", "isDefault", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/policies", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Policy Templates" ], "summary": "Delete a policy template", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/policies", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/policies/{templateId}/assign": { "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Policy Templates" ], "summary": "Assign a policy template to agents", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentIds" ], "properties": { "agentIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "templateId", "assignedAgents", "rulesApplied" ], "properties": { "templateId": { "type": "string" }, "assignedAgents": { "type": "array", "items": { "type": "string" } }, "rulesApplied": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/policies", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/condition-sets": { "get": { "tags": [ "Condition Sets" ], "summary": "List condition sets", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "conditionSets", "limit", "offset" ], "properties": { "conditionSets": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "name", "description", "ownerId", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Condition Sets" ], "summary": "Create a condition set", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "name", "ownerId" ] } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "ownerId", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/condition-sets/{conditionSetId}": { "parameters": [ { "name": "conditionSetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Condition Sets" ], "summary": "Get a condition set", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "ownerId", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "patch": { "tags": [ "Condition Sets" ], "summary": "Update a condition set", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "ownerId", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Condition Sets" ], "summary": "Delete a condition set", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": {} } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/condition-sets/{conditionSetId}/items": { "parameters": [ { "name": "conditionSetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Condition Sets" ], "summary": "List condition set items", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "items", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "conditionSetId", "tenantId", "value", "label", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "conditionSetId": { "type": "string" }, "tenantId": { "type": "string" }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Condition Sets" ], "summary": "Create or upsert a condition set item", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "value" ] } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "conditionSetId", "tenantId", "value", "label", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "conditionSetId": { "type": "string" }, "tenantId": { "type": "string" }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "put": { "tags": [ "Condition Sets" ], "summary": "Replace condition set items", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "value" ] } } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "conditionSetId", "tenantId", "value", "label", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "conditionSetId": { "type": "string" }, "tenantId": { "type": "string" }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/condition-sets/{conditionSetId}/items/{itemId}": { "parameters": [ { "name": "conditionSetId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Condition Sets" ], "summary": "Get a condition set item", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "conditionSetId", "tenantId", "value", "label", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "conditionSetId": { "type": "string" }, "tenantId": { "type": "string" }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "patch": { "tags": [ "Condition Sets" ], "summary": "Update a condition set item", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "conditionSetId", "tenantId", "value", "label", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "conditionSetId": { "type": "string" }, "tenantId": { "type": "string" }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Condition Sets" ], "summary": "Delete a condition set item", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": {} } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/condition-sets": { "get": { "tags": [ "Condition Sets" ], "summary": "List condition sets", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "conditionSets", "limit", "offset" ], "properties": { "conditionSets": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "name", "description", "ownerId", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Condition Sets" ], "summary": "Create a condition set", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "name", "ownerId" ] } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "ownerId", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/condition-sets/{conditionSetId}": { "parameters": [ { "name": "conditionSetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Condition Sets" ], "summary": "Get a condition set", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "ownerId", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "patch": { "tags": [ "Condition Sets" ], "summary": "Update a condition set", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "description", "ownerId", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Condition Sets" ], "summary": "Delete a condition set", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": {} } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/condition-sets/{conditionSetId}/items": { "parameters": [ { "name": "conditionSetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Condition Sets" ], "summary": "List condition set items", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "items", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "conditionSetId", "tenantId", "value", "label", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "conditionSetId": { "type": "string" }, "tenantId": { "type": "string" }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Condition Sets" ], "summary": "Create or upsert a condition set item", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "value" ] } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "conditionSetId", "tenantId", "value", "label", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "conditionSetId": { "type": "string" }, "tenantId": { "type": "string" }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "put": { "tags": [ "Condition Sets" ], "summary": "Replace condition set items", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "value" ] } } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "conditionSetId", "tenantId", "value", "label", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "conditionSetId": { "type": "string" }, "tenantId": { "type": "string" }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/condition-sets/{conditionSetId}/items/{itemId}": { "parameters": [ { "name": "conditionSetId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Condition Sets" ], "summary": "Get a condition set item", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "conditionSetId", "tenantId", "value", "label", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "conditionSetId": { "type": "string" }, "tenantId": { "type": "string" }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "patch": { "tags": [ "Condition Sets" ], "summary": "Update a condition set item", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "conditionSetId", "tenantId", "value", "label", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "conditionSetId": { "type": "string" }, "tenantId": { "type": "string" }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Condition Sets" ], "summary": "Delete a condition set item", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": {} } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/condition-sets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/agents/{agentId}/signers": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Agent Authorization" ], "summary": "List agent signers and authorization keys", "description": "Owner/admin session endpoint for signer inventory. P-256 signers are Privy-style asymmetric authorization keys; HMAC signers use server-issued delegated credentials.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "signers": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Agent Authorization" ], "summary": "Create an agent signer or authorization key", "description": "Requires owner/admin session with recent MFA. Use `keyType: \"p256\"` plus `publicKey` to register an asymmetric authorization key; use `issueCredential: true` for a one-time HMAC delegated signer secret.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "issueCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "anyOf": [ { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, { "allOf": [ { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, { "type": "object", "properties": { "credentialSecret": { "type": "string" } } } ] } ] } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/agents/{agentId}/signers/{signerId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "signerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "tags": [ "Agent Authorization" ], "summary": "Update an agent signer or authorization key", "description": "Authority-changing updates such as key type, public key, permissions, metadata, address, chain family, signer type, or status require recent MFA.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "issueCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Agent Authorization" ], "summary": "Revoke an agent signer or authorization key", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/agents/{agentId}/key-quorums": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Agent Authorization" ], "summary": "List agent key quorums", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quorums": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "agentId", "name", "threshold", "memberSignerIds", "memberQuorumIds", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Agent Authorization" ], "summary": "Create an agent key quorum", "description": "Requires owner/admin session with recent MFA. Quorums can include signer members and child quorum members through `memberSignerIds` and `memberQuorumIds`.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "name", "threshold", "memberSignerIds", "memberQuorumIds", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/agents/{agentId}/key-quorums/{quorumId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "quorumId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "tags": [ "Agent Authorization" ], "summary": "Update an agent key quorum", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "name", "threshold", "memberSignerIds", "memberQuorumIds", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Agent Authorization" ], "summary": "Revoke an agent key quorum", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "name", "threshold", "memberSignerIds", "memberQuorumIds", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/agents/{agentId}/signers": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Agent Authorization" ], "summary": "List agent signers and authorization keys", "description": "Owner/admin session endpoint for signer inventory. P-256 signers are Privy-style asymmetric authorization keys; HMAC signers use server-issued delegated credentials.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "signers": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Agent Authorization" ], "summary": "Create an agent signer or authorization key", "description": "Requires owner/admin session with recent MFA. Use `keyType: \"p256\"` plus `publicKey` to register an asymmetric authorization key; use `issueCredential: true` for a one-time HMAC delegated signer secret.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "issueCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "anyOf": [ { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, { "allOf": [ { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, { "type": "object", "properties": { "credentialSecret": { "type": "string" } } } ] } ] } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/agents/{agentId}/signers/{signerId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "signerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "tags": [ "Agent Authorization" ], "summary": "Update an agent signer or authorization key", "description": "Authority-changing updates such as key type, public key, permissions, metadata, address, chain family, signer type, or status require recent MFA.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "issueCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Agent Authorization" ], "summary": "Revoke an agent signer or authorization key", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/agents/{agentId}/key-quorums": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Agent Authorization" ], "summary": "List agent key quorums", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quorums": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "agentId", "name", "threshold", "memberSignerIds", "memberQuorumIds", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Agent Authorization" ], "summary": "Create an agent key quorum", "description": "Requires owner/admin session with recent MFA. Quorums can include signer members and child quorum members through `memberSignerIds` and `memberQuorumIds`.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "name", "threshold", "memberSignerIds", "memberQuorumIds", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/agents/{agentId}/key-quorums/{quorumId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "quorumId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "tags": [ "Agent Authorization" ], "summary": "Update an agent key quorum", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "name", "threshold", "memberSignerIds", "memberQuorumIds", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Agent Authorization" ], "summary": "Revoke an agent key quorum", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "name", "threshold", "memberSignerIds", "memberQuorumIds", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 }, "memberSignerIds": { "type": "array", "items": { "type": "string" } }, "memberQuorumIds": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/agents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/intents": { "get": { "tags": [ "Intents" ], "summary": "List intents", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] } }, { "name": "intentType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] } }, { "name": "intent_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "wallet_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "intents", "limit", "offset" ], "properties": { "intents": { "type": "array", "items": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Intents" ], "summary": "Create an intent", "description": "Creates a tenant-scoped intent. Privy-style snake_case aliases are accepted for intent_type, wallet_id, resource_type, resource_id, authorization_details, created_by_display_name, expires_at, and ttl_seconds.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "resourceType": { "type": [ "string", "null" ] }, "resource_type": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "ttlSeconds": { "type": "integer", "minimum": 1 }, "ttl_seconds": { "type": "integer", "minimum": 1 } }, "anyOf": [ { "required": [ "intentType" ] }, { "required": [ "intent_type" ] } ] } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/intents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/intents/{intentId}": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Intents" ], "summary": "Get an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/intents/{intentId}/authorize": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Authorize an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/intents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/intents/{intentId}/approve": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Approve an intent", "description": "Alias for /intents/{intentId}/authorize.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/intents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/intents/{intentId}/reject": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Reject an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/intents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/intents/{intentId}/execute": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Execute an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/intents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/intents/{intentId}/fail": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Fail an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/intents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/intents/{intentId}/cancel": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Cancel an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/intents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/intents/{intentId}/expire": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Expire an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/intents", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/intents": { "get": { "tags": [ "Intents" ], "summary": "List intents", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] } }, { "name": "intentType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] } }, { "name": "intent_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "wallet_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "intents", "limit", "offset" ], "properties": { "intents": { "type": "array", "items": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Intents" ], "summary": "Create an intent", "description": "Creates a tenant-scoped intent. Privy-style snake_case aliases are accepted for intent_type, wallet_id, resource_type, resource_id, authorization_details, created_by_display_name, expires_at, and ttl_seconds.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "resourceType": { "type": [ "string", "null" ] }, "resource_type": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "ttlSeconds": { "type": "integer", "minimum": 1 }, "ttl_seconds": { "type": "integer", "minimum": 1 } }, "anyOf": [ { "required": [ "intentType" ] }, { "required": [ "intent_type" ] } ] } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/intents/{intentId}": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Intents" ], "summary": "Get an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/intents/{intentId}/authorize": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Authorize an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/intents/{intentId}/approve": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Approve an intent", "description": "Alias for /intents/{intentId}/authorize.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/intents/{intentId}/reject": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Reject an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/intents/{intentId}/execute": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Execute an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/intents/{intentId}/fail": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Fail an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/intents/{intentId}/cancel": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Cancel an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/intents/{intentId}/expire": { "parameters": [ { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Intents" ], "summary": "Expire an intent", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason": { "type": "string" }, "executionResult": { "type": "object", "additionalProperties": true }, "execution_result": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "intent_id", "intentType", "intent_type", "status", "payload", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "intent_id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "wallet_id": { "type": [ "string", "null" ] }, "intentType": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "intent_type": { "type": "string", "enum": [ "rpc", "transfer", "wallet_update", "policy_update", "policy_rule_create", "policy_rule_delete", "policy_rule_update", "quorum_update", "wallet_action", "provider-action" ] }, "status": { "type": "string", "enum": [ "pending", "authorized", "executing", "executed", "failed", "rejected", "canceled", "expired" ] }, "resourceType": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "createdByType": { "type": "string" }, "createdById": { "type": [ "string", "null" ] }, "created_by_id": { "type": [ "string", "null" ] }, "createdByDisplayName": { "type": [ "string", "null" ] }, "created_by_display_name": { "type": [ "string", "null" ] }, "authorizationDetails": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authorization_details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "executionResult": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_result": { "type": [ "object", "null" ], "additionalProperties": true }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "integer", "null" ] }, "authorizedBy": { "type": [ "string", "null" ] }, "authorized_by": { "type": [ "string", "null" ] }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "created_at": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/user/me/wallet/import/init": { "post": { "tags": [ "Wallets" ], "summary": "Initialize encrypted authenticated user-wallet key import", "description": "Requires a personal authenticated user session with recent MFA plus audited user-wallet import feature flags. Returns a short-lived X25519 public key and tenant/app/user/wallet AAD for a one-time encrypted private-key import session. Responses are no-store and do not contain private-key material.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "chain" ], "properties": { "chain": { "type": "string", "enum": [ "evm", "solana" ] }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "wallet_index": { "type": "integer", "minimum": 0, "maximum": 255 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "importSessionId", "publicKey", "algorithm", "expiresAt", "aad" ], "properties": { "importSessionId": { "type": "string" }, "publicKey": { "type": "string", "description": "Base64url DER-encoded X25519 SPKI public key for this one-time user-wallet import session." }, "algorithm": { "type": "string", "const": "X25519-HKDF-SHA256-AES-256-GCM" }, "expiresAt": { "type": "string", "format": "date-time" }, "aad": { "type": "object", "required": [ "importSessionId", "tenantId", "userId", "agentId", "chain", "walletIndex" ], "properties": { "importSessionId": { "type": "string" }, "tenantId": { "type": "string" }, "userId": { "type": "string" }, "agentId": { "type": "string" }, "chain": { "type": "string", "enum": [ "evm", "solana" ] }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "appClientId": { "type": [ "string", "null" ] } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/user", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/user/me/wallet/import/submit": { "post": { "tags": [ "Wallets" ], "summary": "Submit encrypted authenticated user-wallet key import", "description": "Consumes a one-time user-wallet import session bound to the authenticated user, personal tenant, walletIndex, and app client when present. Plaintext `privateKey` fields are rejected; audit and webhook metadata record only chain/session/address metadata.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "importSessionId", "ephemeralPublicKey", "iv", "ciphertext", "tag" ], "properties": { "importSessionId": { "type": "string" }, "ephemeralPublicKey": { "type": "string", "description": "Base64url DER-encoded X25519 SPKI public key generated by the client." }, "iv": { "type": "string", "description": "Base64url AES-GCM nonce, 12 bytes before encoding." }, "ciphertext": { "type": "string", "description": "Base64url encrypted private key bytes. Plaintext privateKey is rejected." }, "tag": { "type": "string", "description": "Base64url AES-GCM authentication tag." }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "wallet_index": { "type": "integer", "minimum": 0, "maximum": 255 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "agentId", "walletAddress", "chain", "walletIndex", "imported" ], "properties": { "agentId": { "type": "string" }, "walletAddress": { "type": "string" }, "chain": { "type": "string", "enum": [ "evm", "solana" ] }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "imported": { "type": "boolean", "const": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/user", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/user/me/wallet/signers": { "get": { "tags": [ "Wallets" ], "summary": "List authenticated user wallet signers", "description": "Requires a personal authenticated user session with recent MFA. Supports walletIndex/wallet_index selectors for indexed embedded wallets. Credential secrets are never returned by list responses.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "walletIndex", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 255 } }, { "name": "wallet_index", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 255 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "signers": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Wallets" ], "summary": "Create an authenticated user wallet signer credential", "description": "Requires a personal authenticated user session with recent MFA. Creates a bounded HMAC signer credential for signing-only permissions on the selected embedded wallet. The one-time credentialSecret is returned only in this create response.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "wallet_index": { "type": "integer", "minimum": 0, "maximum": 255 }, "signerType": { "type": "string", "enum": [ "delegated", "service" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac" ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "allOf": [ { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, { "type": "object", "properties": { "credentialSecret": { "type": "string" } } } ] } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/user", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/user/me/wallet/signers/{signerId}": { "parameters": [ { "name": "signerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Wallets" ], "summary": "Revoke an authenticated user wallet signer", "description": "Requires a personal authenticated user session with recent MFA and a matching walletIndex/wallet_index selector when revoking a signer on an indexed embedded wallet.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "walletIndex", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 255 } }, { "name": "wallet_index", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 255 } }, { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/user", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/user/me/wallet/import/init": { "post": { "tags": [ "Wallets" ], "summary": "Initialize encrypted authenticated user-wallet key import", "description": "Requires a personal authenticated user session with recent MFA plus audited user-wallet import feature flags. Returns a short-lived X25519 public key and tenant/app/user/wallet AAD for a one-time encrypted private-key import session. Responses are no-store and do not contain private-key material.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "chain" ], "properties": { "chain": { "type": "string", "enum": [ "evm", "solana" ] }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "wallet_index": { "type": "integer", "minimum": 0, "maximum": 255 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "importSessionId", "publicKey", "algorithm", "expiresAt", "aad" ], "properties": { "importSessionId": { "type": "string" }, "publicKey": { "type": "string", "description": "Base64url DER-encoded X25519 SPKI public key for this one-time user-wallet import session." }, "algorithm": { "type": "string", "const": "X25519-HKDF-SHA256-AES-256-GCM" }, "expiresAt": { "type": "string", "format": "date-time" }, "aad": { "type": "object", "required": [ "importSessionId", "tenantId", "userId", "agentId", "chain", "walletIndex" ], "properties": { "importSessionId": { "type": "string" }, "tenantId": { "type": "string" }, "userId": { "type": "string" }, "agentId": { "type": "string" }, "chain": { "type": "string", "enum": [ "evm", "solana" ] }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "appClientId": { "type": [ "string", "null" ] } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/user/me/wallet/import/submit": { "post": { "tags": [ "Wallets" ], "summary": "Submit encrypted authenticated user-wallet key import", "description": "Consumes a one-time user-wallet import session bound to the authenticated user, personal tenant, walletIndex, and app client when present. Plaintext `privateKey` fields are rejected; audit and webhook metadata record only chain/session/address metadata.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "importSessionId", "ephemeralPublicKey", "iv", "ciphertext", "tag" ], "properties": { "importSessionId": { "type": "string" }, "ephemeralPublicKey": { "type": "string", "description": "Base64url DER-encoded X25519 SPKI public key generated by the client." }, "iv": { "type": "string", "description": "Base64url AES-GCM nonce, 12 bytes before encoding." }, "ciphertext": { "type": "string", "description": "Base64url encrypted private key bytes. Plaintext privateKey is rejected." }, "tag": { "type": "string", "description": "Base64url AES-GCM authentication tag." }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "wallet_index": { "type": "integer", "minimum": 0, "maximum": 255 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "agentId", "walletAddress", "chain", "walletIndex", "imported" ], "properties": { "agentId": { "type": "string" }, "walletAddress": { "type": "string" }, "chain": { "type": "string", "enum": [ "evm", "solana" ] }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "imported": { "type": "boolean", "const": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/user/me/wallet/signers": { "get": { "tags": [ "Wallets" ], "summary": "List authenticated user wallet signers", "description": "Requires a personal authenticated user session with recent MFA. Supports walletIndex/wallet_index selectors for indexed embedded wallets. Credential secrets are never returned by list responses.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "walletIndex", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 255 } }, { "name": "wallet_index", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 255 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "revoked" ] } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "signers": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Wallets" ], "summary": "Create an authenticated user wallet signer credential", "description": "Requires a personal authenticated user session with recent MFA. Creates a bounded HMAC signer credential for signing-only permissions on the selected embedded wallet. The one-time credentialSecret is returned only in this create response.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "wallet_index": { "type": "integer", "minimum": 0, "maximum": 255 }, "signerType": { "type": "string", "enum": [ "delegated", "service" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac" ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "allOf": [ { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, { "type": "object", "properties": { "credentialSecret": { "type": "string" } } } ] } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/user/me/wallet/signers/{signerId}": { "parameters": [ { "name": "signerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Wallets" ], "summary": "Revoke an authenticated user wallet signer", "description": "Requires a personal authenticated user session with recent MFA and a matching walletIndex/wallet_index selector when revoking a signer on an indexed embedded wallet.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "walletIndex", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 255 } }, { "name": "wallet_index", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 255 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "signerType", "subjectType", "subjectId", "keyType", "publicKey", "permissions", "metadata", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "signerType": { "type": "string", "enum": [ "owner", "delegated", "service", "quorum_member" ] }, "subjectType": { "type": "string", "enum": [ "user", "wallet", "api_key", "external" ] }, "subjectId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "hmac", "p256" ] }, "publicKey": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "chainFamily": { "type": [ "string", "null" ], "enum": [ "evm", "solana", null ] }, "label": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "hasCredential": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/wallets/batch": { "post": { "tags": [ "Wallets" ], "summary": "Create multiple server wallets", "description": "Privy-style batch wallet alias. `externalId` maps to Steward's immutable per-tenant wallet platform ID.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallets": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "object", "required": [ "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "platformId": { "type": "string" } } } }, "applyPolicies": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": true } } }, "required": [ "wallets" ] } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "created", "errors" ], "properties": { "created": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "name", "walletAddress", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "walletAddress": { "type": "string" }, "walletAddresses": { "type": "object", "properties": { "evm": { "type": "string" }, "solana": { "type": "string" } } }, "platformId": { "type": [ "string", "null" ] }, "erc8004TokenId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } } }, "errors": { "type": "array", "items": { "type": "object", "required": [ "id", "error" ], "properties": { "id": { "type": "string" }, "error": { "type": "string" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/wallets/batch", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/wallets/batch": { "post": { "tags": [ "Wallets" ], "summary": "Create multiple server wallets", "description": "Privy-style batch wallet alias. `externalId` maps to Steward's immutable per-tenant wallet platform ID.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallets": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "object", "required": [ "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "platformId": { "type": "string" } } } }, "applyPolicies": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": true } } }, "required": [ "wallets" ] } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "created", "errors" ], "properties": { "created": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "name", "walletAddress", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "walletAddress": { "type": "string" }, "walletAddresses": { "type": "object", "properties": { "evm": { "type": "string" }, "solana": { "type": "string" } } }, "platformId": { "type": [ "string", "null" ] }, "erc8004TokenId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } } }, "errors": { "type": "array", "items": { "type": "object", "required": [ "id", "error" ], "properties": { "id": { "type": "string" }, "error": { "type": "string" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/wallets/batch", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters": { "get": { "tags": [ "Adapters" ], "summary": "Discover configured financial-service adapters", "description": "Returns the tenant-visible adapter registry. Adapter routes are tenant-authenticated, no-store, and fund-moving build endpoints return unsigned intents gated by policy/spend checks before anything signable is exposed.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "adapters" ], "properties": { "adapters": { "type": "object", "description": "Provider-neutral adapter registry for swap, earn, bridge, Spark BTC/Lightning, exchange, fiat, KYC/TOS, and custodial seams. Production provider availability depends on tenant configuration.", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/adapters/swap/quote": { "post": { "tags": [ "Adapters" ], "summary": "Quote a swap through the configured adapter", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fromToken", "toToken", "amount", "chainId" ], "properties": { "agentId": { "type": "string" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amount": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 }, "slippageBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quote": { "type": "object", "required": [ "provider", "quoteId", "fromToken", "toToken", "amountIn", "amountOut", "chainId" ], "properties": { "provider": { "type": "string" }, "quoteId": { "type": "string" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amountIn": { "type": "string" }, "amountOut": { "type": "string" }, "minAmountOut": { "type": "string" }, "feeAmount": { "type": "string" }, "chainId": { "type": "integer" }, "slippageBps": { "type": "integer" }, "expiresAt": { "type": "integer" }, "route": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/swap/build": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned swap intent after policy/spend checks", "description": "Returns an unsigned intent only. The caller must still route the artifact through the vault signing path before funds move.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote" ], "properties": { "agentId": { "type": "string" }, "quote": { "type": "object", "required": [ "provider", "quoteId", "fromToken", "toToken", "amountIn", "amountOut", "chainId" ], "properties": { "provider": { "type": "string" }, "quoteId": { "type": "string" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amountIn": { "type": "string" }, "amountOut": { "type": "string" }, "minAmountOut": { "type": "string" }, "feeAmount": { "type": "string" }, "chainId": { "type": "integer" }, "slippageBps": { "type": "integer" }, "expiresAt": { "type": "integer" }, "route": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/earn/vaults": { "get": { "tags": [ "Adapters" ], "summary": "List earn vaults", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "chainId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "vaults": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "chainId": { "type": "integer" }, "asset": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "shareToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "apy": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/adapters/earn/vaults/{vault}/position": { "parameters": [ { "name": "vault", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": false, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Get an earn vault position", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "position": { "type": "object", "required": [ "vault", "owner", "assets", "shares" ], "properties": { "vault": { "type": "string" }, "owner": { "type": "string" }, "assets": { "type": "string" }, "shares": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/adapters/earn/deposit": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned earn deposit intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vault", "assets" ], "properties": { "agentId": { "type": "string" }, "vault": { "type": "string" }, "assets": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/earn/withdraw": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned earn withdraw intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vault", "shares" ], "properties": { "agentId": { "type": "string" }, "vault": { "type": "string" }, "shares": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/bridge/quote": { "post": { "tags": [ "Adapters" ], "summary": "Quote a bridge transfer", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fromChainId", "toChainId", "fromToken", "toToken", "amount", "recipient" ], "properties": { "agentId": { "type": "string" }, "fromChainId": { "type": "integer", "minimum": 1 }, "toChainId": { "type": "integer", "minimum": 1 }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amount": { "type": "string" }, "recipient": { "type": "string" }, "slippageBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quote": { "type": "object", "required": [ "provider", "quoteId", "fromChainId", "toChainId", "amountIn", "amountOut" ], "properties": { "provider": { "type": "string" }, "quoteId": { "type": "string" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amountIn": { "type": "string" }, "amountOut": { "type": "string" }, "minAmountOut": { "type": "string" }, "feeAmount": { "type": "string" }, "recipient": { "type": "string" }, "route": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "slippageBps": { "type": "integer" }, "expiresAt": { "type": "integer" }, "direction": { "type": "string" }, "executionMode": { "type": "string", "enum": [ "unsigned-transaction", "external-handoff" ] }, "handoffUrl": { "type": "string", "format": "uri" }, "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "feeScope": { "type": "string", "enum": [ "final", "global-estimate", "not-applicable" ] }, "feeObservedSlot": { "type": "integer", "minimum": 0 }, "feeObservedAt": { "type": "integer", "minimum": 0 }, "notices": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/bridge/build": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned bridge intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "owner", "quote" ], "properties": { "agentId": { "type": "string" }, "owner": { "type": "string" }, "quote": { "type": "object", "required": [ "provider", "quoteId", "fromChainId", "toChainId", "amountIn", "amountOut" ], "properties": { "provider": { "type": "string" }, "quoteId": { "type": "string" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amountIn": { "type": "string" }, "amountOut": { "type": "string" }, "minAmountOut": { "type": "string" }, "feeAmount": { "type": "string" }, "recipient": { "type": "string" }, "route": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "slippageBps": { "type": "integer" }, "expiresAt": { "type": "integer" }, "direction": { "type": "string" }, "executionMode": { "type": "string", "enum": [ "unsigned-transaction", "external-handoff" ] }, "handoffUrl": { "type": "string", "format": "uri" }, "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "feeScope": { "type": "string", "enum": [ "final", "global-estimate", "not-applicable" ] }, "feeObservedSlot": { "type": "integer", "minimum": 0 }, "feeObservedAt": { "type": "integer", "minimum": 0 }, "notices": { "type": "array", "items": { "type": "string" } } } }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "oneOf": [ { "type": "object", "required": [ "unsignedIntent" ], "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } }, { "type": "object", "required": [ "handoff" ], "properties": { "handoff": { "type": "object", "required": [ "kind", "category", "provider", "quoteId", "direction", "url", "fromChainId", "toChainId", "amountIn", "estimatedUsd", "recipient", "expiresAt", "notices", "feeBps", "feeScope", "feeObservedAt" ], "properties": { "kind": { "type": "string", "const": "external-handoff" }, "category": { "type": "string", "const": "bridge" }, "provider": { "type": "string" }, "quoteId": { "type": "string" }, "direction": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "amountIn": { "type": "string" }, "estimatedUsd": { "type": "number", "exclusiveMinimum": 0 }, "recipient": { "type": "string" }, "recipientSensitive": { "type": "boolean" }, "expiresAt": { "type": "integer" }, "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "feeScope": { "type": "string", "enum": [ "global-estimate", "owner-observed", "not-applicable" ] }, "feeObservedSlot": { "type": "integer", "minimum": 0 }, "feeObservedAt": { "type": "integer", "minimum": 0 }, "notices": { "type": "array", "items": { "type": "string" } } } } } } ] } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/bridge/sessions": { "post": { "tags": [ "Adapters" ], "summary": "Create a bridge session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote" ], "properties": { "userId": { "type": "string" }, "quote": { "type": "object", "required": [ "provider", "quoteId", "fromChainId", "toChainId", "amountIn", "amountOut" ], "properties": { "provider": { "type": "string" }, "quoteId": { "type": "string" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amountIn": { "type": "string" }, "amountOut": { "type": "string" }, "minAmountOut": { "type": "string" }, "feeAmount": { "type": "string" }, "recipient": { "type": "string" }, "route": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "slippageBps": { "type": "integer" }, "expiresAt": { "type": "integer" }, "direction": { "type": "string" }, "executionMode": { "type": "string", "enum": [ "unsigned-transaction", "external-handoff" ] }, "handoffUrl": { "type": "string", "format": "uri" }, "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "feeScope": { "type": "string", "enum": [ "final", "global-estimate", "not-applicable" ] }, "feeObservedSlot": { "type": "integer", "minimum": 0 }, "feeObservedAt": { "type": "integer", "minimum": 0 }, "notices": { "type": "array", "items": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "session": { "type": "object", "required": [ "id", "provider", "quoteId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "quoteId": { "type": "string" }, "status": { "type": "string" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "recipient": { "type": "string" }, "createdAt": { "type": "integer" }, "direction": { "type": "string" }, "executionMode": { "type": "string", "enum": [ "unsigned-transaction", "external-handoff" ] }, "handoffUrl": { "type": "string", "format": "uri" }, "recipientSensitive": { "type": "boolean" }, "notices": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/bridge/sessions/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Get a bridge session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "session": { "type": "object", "required": [ "id", "provider", "quoteId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "quoteId": { "type": "string" }, "status": { "type": "string" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "recipient": { "type": "string" }, "createdAt": { "type": "integer" }, "direction": { "type": "string" }, "executionMode": { "type": "string", "enum": [ "unsigned-transaction", "external-handoff" ] }, "handoffUrl": { "type": "string", "format": "uri" }, "recipientSensitive": { "type": "boolean" }, "notices": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/adapters/spark/wallets": { "post": { "tags": [ "Adapters" ], "summary": "Create a mock Spark wallet DTO", "description": "Creates provider-neutral Spark wallet metadata. The mock never creates or stores key material.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "testnet", "signet" ] }, "label": { "type": "string" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "wallet": { "type": "object", "required": [ "id", "provider", "userId", "network", "status", "sparkAddress", "identityPublicKey", "createdAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "testnet", "signet" ] }, "status": { "type": "string", "enum": [ "created", "active", "disabled" ] }, "sparkAddress": { "type": "string" }, "identityPublicKey": { "type": "string" }, "createdAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/spark/wallets/{walletId}": { "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Get a Spark wallet DTO", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "wallet": { "type": "object", "required": [ "id", "provider", "userId", "network", "status", "sparkAddress", "identityPublicKey", "createdAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "testnet", "signet" ] }, "status": { "type": "string", "enum": [ "created", "active", "disabled" ] }, "sparkAddress": { "type": "string" }, "identityPublicKey": { "type": "string" }, "createdAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/adapters/spark/wallets/{walletId}/balance": { "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Read Spark BTC/Lightning balances", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "balance": { "type": "object", "required": [ "walletId", "provider", "network", "btcSats", "lightningSats", "updatedAt" ], "properties": { "walletId": { "type": "string" }, "provider": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "testnet", "signet" ] }, "btcSats": { "type": "string" }, "lightningSats": { "type": "string" }, "sparkTokenBalances": { "type": "array", "items": { "type": "object", "required": [ "tokenId", "amount" ], "properties": { "tokenId": { "type": "string" }, "amount": { "type": "string" } } } }, "updatedAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/adapters/spark/static-btc-deposits": { "post": { "tags": [ "Adapters" ], "summary": "Create a static BTC deposit quote", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId" ], "properties": { "walletId": { "type": "string" }, "amountSats": { "type": "string" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quote": { "type": "object", "required": [ "id", "provider", "walletId", "network", "depositAddress", "status", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "walletId": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "testnet", "signet" ] }, "depositAddress": { "type": "string" }, "amountSats": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "funded", "claimed", "expired" ] }, "expiresAt": { "type": "integer" }, "createdAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/spark/static-btc-deposits/claim": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned static BTC deposit claim intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "quoteId" ], "properties": { "agentId": { "type": "string" }, "walletId": { "type": "string" }, "quoteId": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/spark/lightning/invoices": { "post": { "tags": [ "Adapters" ], "summary": "Create a Lightning invoice DTO", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "amountSats" ], "properties": { "walletId": { "type": "string" }, "amountSats": { "type": "string" }, "memo": { "type": "string" }, "expiresInSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "invoice": { "type": "object", "required": [ "id", "provider", "walletId", "amountSats", "paymentRequest", "status", "createdAt", "expiresAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "walletId": { "type": "string" }, "amountSats": { "type": "string" }, "memo": { "type": "string" }, "paymentRequest": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "paid", "expired", "canceled" ] }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/spark/lightning/invoices/{invoiceId}": { "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Get a Lightning invoice DTO", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "invoice": { "type": "object", "required": [ "id", "provider", "walletId", "amountSats", "paymentRequest", "status", "createdAt", "expiresAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "walletId": { "type": "string" }, "amountSats": { "type": "string" }, "memo": { "type": "string" }, "paymentRequest": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "paid", "expired", "canceled" ] }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/adapters/spark/lightning/pay": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned Lightning payment intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "paymentRequest" ], "properties": { "agentId": { "type": "string" }, "walletId": { "type": "string" }, "paymentRequest": { "type": "string" }, "maxFeeSats": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/spark/transfers": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned Spark BTC transfer intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "recipient", "amountSats" ], "properties": { "agentId": { "type": "string" }, "walletId": { "type": "string" }, "recipient": { "type": "string" }, "amountSats": { "type": "string" }, "memo": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/spark/token-transfers": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned Spark token transfer intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "recipient", "tokenId", "amount" ], "properties": { "agentId": { "type": "string" }, "walletId": { "type": "string" }, "recipient": { "type": "string" }, "tokenId": { "type": "string" }, "amount": { "type": "string" }, "memo": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/spark/identity/sign": { "post": { "tags": [ "Adapters" ], "summary": "Request Spark identity-key signing", "description": "The mock Spark adapter fails closed with 501 and never fabricates signatures. A real provider must be configured before this can return a signature.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "payload" ], "properties": { "walletId": { "type": "string" }, "payload": { "type": "string" } } } } } }, "responses": { "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "501": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/exchange/sessions": { "post": { "tags": [ "Adapters" ], "summary": "Create an exchange embed session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "returnUrl" ], "properties": { "userId": { "type": "string" }, "provider": { "type": "string", "enum": [ "kraken", "coinbase", "binance", "mock" ] }, "returnUrl": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "locale": { "type": "string" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "session": { "type": "object", "required": [ "id", "provider", "userId", "tenantId", "status", "url" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "tenantId": { "type": "string" }, "status": { "type": "string" }, "url": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/adapters/exchange/sessions/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Get an exchange embed session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "session": { "type": "object", "required": [ "id", "provider", "userId", "tenantId", "status", "url" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "tenantId": { "type": "string" }, "status": { "type": "string" }, "url": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/adapters/exchange/accounts": { "get": { "tags": [ "Adapters" ], "summary": "List linked exchange accounts", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "required": [ "id", "provider", "userId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "externalAccountId": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "integer" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/adapters/exchange/accounts/{accountId}": { "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Adapters" ], "summary": "Revoke a linked exchange account", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "account": { "type": "object", "required": [ "id", "provider", "userId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "externalAccountId": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters": { "get": { "tags": [ "Adapters" ], "summary": "Discover configured financial-service adapters", "description": "Returns the tenant-visible adapter registry. Adapter routes are tenant-authenticated, no-store, and fund-moving build endpoints return unsigned intents gated by policy/spend checks before anything signable is exposed.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "adapters" ], "properties": { "adapters": { "type": "object", "description": "Provider-neutral adapter registry for swap, earn, bridge, Spark BTC/Lightning, exchange, fiat, KYC/TOS, and custodial seams. Production provider availability depends on tenant configuration.", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/adapters/swap/quote": { "post": { "tags": [ "Adapters" ], "summary": "Quote a swap through the configured adapter", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fromToken", "toToken", "amount", "chainId" ], "properties": { "agentId": { "type": "string" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amount": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 }, "slippageBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quote": { "type": "object", "required": [ "provider", "quoteId", "fromToken", "toToken", "amountIn", "amountOut", "chainId" ], "properties": { "provider": { "type": "string" }, "quoteId": { "type": "string" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amountIn": { "type": "string" }, "amountOut": { "type": "string" }, "minAmountOut": { "type": "string" }, "feeAmount": { "type": "string" }, "chainId": { "type": "integer" }, "slippageBps": { "type": "integer" }, "expiresAt": { "type": "integer" }, "route": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/swap/build": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned swap intent after policy/spend checks", "description": "Returns an unsigned intent only. The caller must still route the artifact through the vault signing path before funds move.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote" ], "properties": { "agentId": { "type": "string" }, "quote": { "type": "object", "required": [ "provider", "quoteId", "fromToken", "toToken", "amountIn", "amountOut", "chainId" ], "properties": { "provider": { "type": "string" }, "quoteId": { "type": "string" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amountIn": { "type": "string" }, "amountOut": { "type": "string" }, "minAmountOut": { "type": "string" }, "feeAmount": { "type": "string" }, "chainId": { "type": "integer" }, "slippageBps": { "type": "integer" }, "expiresAt": { "type": "integer" }, "route": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/earn/vaults": { "get": { "tags": [ "Adapters" ], "summary": "List earn vaults", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "chainId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "vaults": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "chainId": { "type": "integer" }, "asset": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "shareToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "apy": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/adapters/earn/vaults/{vault}/position": { "parameters": [ { "name": "vault", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": false, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Get an earn vault position", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "position": { "type": "object", "required": [ "vault", "owner", "assets", "shares" ], "properties": { "vault": { "type": "string" }, "owner": { "type": "string" }, "assets": { "type": "string" }, "shares": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/adapters/earn/deposit": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned earn deposit intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vault", "assets" ], "properties": { "agentId": { "type": "string" }, "vault": { "type": "string" }, "assets": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/earn/withdraw": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned earn withdraw intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vault", "shares" ], "properties": { "agentId": { "type": "string" }, "vault": { "type": "string" }, "shares": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/bridge/quote": { "post": { "tags": [ "Adapters" ], "summary": "Quote a bridge transfer", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fromChainId", "toChainId", "fromToken", "toToken", "amount", "recipient" ], "properties": { "agentId": { "type": "string" }, "fromChainId": { "type": "integer", "minimum": 1 }, "toChainId": { "type": "integer", "minimum": 1 }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amount": { "type": "string" }, "recipient": { "type": "string" }, "slippageBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quote": { "type": "object", "required": [ "provider", "quoteId", "fromChainId", "toChainId", "amountIn", "amountOut" ], "properties": { "provider": { "type": "string" }, "quoteId": { "type": "string" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amountIn": { "type": "string" }, "amountOut": { "type": "string" }, "minAmountOut": { "type": "string" }, "feeAmount": { "type": "string" }, "recipient": { "type": "string" }, "route": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "slippageBps": { "type": "integer" }, "expiresAt": { "type": "integer" }, "direction": { "type": "string" }, "executionMode": { "type": "string", "enum": [ "unsigned-transaction", "external-handoff" ] }, "handoffUrl": { "type": "string", "format": "uri" }, "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "feeScope": { "type": "string", "enum": [ "final", "global-estimate", "not-applicable" ] }, "feeObservedSlot": { "type": "integer", "minimum": 0 }, "feeObservedAt": { "type": "integer", "minimum": 0 }, "notices": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/bridge/build": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned bridge intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "owner", "quote" ], "properties": { "agentId": { "type": "string" }, "owner": { "type": "string" }, "quote": { "type": "object", "required": [ "provider", "quoteId", "fromChainId", "toChainId", "amountIn", "amountOut" ], "properties": { "provider": { "type": "string" }, "quoteId": { "type": "string" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amountIn": { "type": "string" }, "amountOut": { "type": "string" }, "minAmountOut": { "type": "string" }, "feeAmount": { "type": "string" }, "recipient": { "type": "string" }, "route": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "slippageBps": { "type": "integer" }, "expiresAt": { "type": "integer" }, "direction": { "type": "string" }, "executionMode": { "type": "string", "enum": [ "unsigned-transaction", "external-handoff" ] }, "handoffUrl": { "type": "string", "format": "uri" }, "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "feeScope": { "type": "string", "enum": [ "final", "global-estimate", "not-applicable" ] }, "feeObservedSlot": { "type": "integer", "minimum": 0 }, "feeObservedAt": { "type": "integer", "minimum": 0 }, "notices": { "type": "array", "items": { "type": "string" } } } }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "oneOf": [ { "type": "object", "required": [ "unsignedIntent" ], "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } }, { "type": "object", "required": [ "handoff" ], "properties": { "handoff": { "type": "object", "required": [ "kind", "category", "provider", "quoteId", "direction", "url", "fromChainId", "toChainId", "amountIn", "estimatedUsd", "recipient", "expiresAt", "notices", "feeBps", "feeScope", "feeObservedAt" ], "properties": { "kind": { "type": "string", "const": "external-handoff" }, "category": { "type": "string", "const": "bridge" }, "provider": { "type": "string" }, "quoteId": { "type": "string" }, "direction": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "amountIn": { "type": "string" }, "estimatedUsd": { "type": "number", "exclusiveMinimum": 0 }, "recipient": { "type": "string" }, "recipientSensitive": { "type": "boolean" }, "expiresAt": { "type": "integer" }, "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "feeScope": { "type": "string", "enum": [ "global-estimate", "owner-observed", "not-applicable" ] }, "feeObservedSlot": { "type": "integer", "minimum": 0 }, "feeObservedAt": { "type": "integer", "minimum": 0 }, "notices": { "type": "array", "items": { "type": "string" } } } } } } ] } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/bridge/sessions": { "post": { "tags": [ "Adapters" ], "summary": "Create a bridge session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote" ], "properties": { "userId": { "type": "string" }, "quote": { "type": "object", "required": [ "provider", "quoteId", "fromChainId", "toChainId", "amountIn", "amountOut" ], "properties": { "provider": { "type": "string" }, "quoteId": { "type": "string" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "fromToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "toToken": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 } } }, "amountIn": { "type": "string" }, "amountOut": { "type": "string" }, "minAmountOut": { "type": "string" }, "feeAmount": { "type": "string" }, "recipient": { "type": "string" }, "route": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "slippageBps": { "type": "integer" }, "expiresAt": { "type": "integer" }, "direction": { "type": "string" }, "executionMode": { "type": "string", "enum": [ "unsigned-transaction", "external-handoff" ] }, "handoffUrl": { "type": "string", "format": "uri" }, "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "feeScope": { "type": "string", "enum": [ "final", "global-estimate", "not-applicable" ] }, "feeObservedSlot": { "type": "integer", "minimum": 0 }, "feeObservedAt": { "type": "integer", "minimum": 0 }, "notices": { "type": "array", "items": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "session": { "type": "object", "required": [ "id", "provider", "quoteId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "quoteId": { "type": "string" }, "status": { "type": "string" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "recipient": { "type": "string" }, "createdAt": { "type": "integer" }, "direction": { "type": "string" }, "executionMode": { "type": "string", "enum": [ "unsigned-transaction", "external-handoff" ] }, "handoffUrl": { "type": "string", "format": "uri" }, "recipientSensitive": { "type": "boolean" }, "notices": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/bridge/sessions/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Get a bridge session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "session": { "type": "object", "required": [ "id", "provider", "quoteId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "quoteId": { "type": "string" }, "status": { "type": "string" }, "fromChainId": { "type": "integer" }, "toChainId": { "type": "integer" }, "recipient": { "type": "string" }, "createdAt": { "type": "integer" }, "direction": { "type": "string" }, "executionMode": { "type": "string", "enum": [ "unsigned-transaction", "external-handoff" ] }, "handoffUrl": { "type": "string", "format": "uri" }, "recipientSensitive": { "type": "boolean" }, "notices": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/adapters/spark/wallets": { "post": { "tags": [ "Adapters" ], "summary": "Create a mock Spark wallet DTO", "description": "Creates provider-neutral Spark wallet metadata. The mock never creates or stores key material.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "testnet", "signet" ] }, "label": { "type": "string" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "wallet": { "type": "object", "required": [ "id", "provider", "userId", "network", "status", "sparkAddress", "identityPublicKey", "createdAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "testnet", "signet" ] }, "status": { "type": "string", "enum": [ "created", "active", "disabled" ] }, "sparkAddress": { "type": "string" }, "identityPublicKey": { "type": "string" }, "createdAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/spark/wallets/{walletId}": { "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Get a Spark wallet DTO", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "wallet": { "type": "object", "required": [ "id", "provider", "userId", "network", "status", "sparkAddress", "identityPublicKey", "createdAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "testnet", "signet" ] }, "status": { "type": "string", "enum": [ "created", "active", "disabled" ] }, "sparkAddress": { "type": "string" }, "identityPublicKey": { "type": "string" }, "createdAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/adapters/spark/wallets/{walletId}/balance": { "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Read Spark BTC/Lightning balances", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "balance": { "type": "object", "required": [ "walletId", "provider", "network", "btcSats", "lightningSats", "updatedAt" ], "properties": { "walletId": { "type": "string" }, "provider": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "testnet", "signet" ] }, "btcSats": { "type": "string" }, "lightningSats": { "type": "string" }, "sparkTokenBalances": { "type": "array", "items": { "type": "object", "required": [ "tokenId", "amount" ], "properties": { "tokenId": { "type": "string" }, "amount": { "type": "string" } } } }, "updatedAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/adapters/spark/static-btc-deposits": { "post": { "tags": [ "Adapters" ], "summary": "Create a static BTC deposit quote", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId" ], "properties": { "walletId": { "type": "string" }, "amountSats": { "type": "string" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quote": { "type": "object", "required": [ "id", "provider", "walletId", "network", "depositAddress", "status", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "walletId": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "testnet", "signet" ] }, "depositAddress": { "type": "string" }, "amountSats": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "funded", "claimed", "expired" ] }, "expiresAt": { "type": "integer" }, "createdAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/spark/static-btc-deposits/claim": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned static BTC deposit claim intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "quoteId" ], "properties": { "agentId": { "type": "string" }, "walletId": { "type": "string" }, "quoteId": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/spark/lightning/invoices": { "post": { "tags": [ "Adapters" ], "summary": "Create a Lightning invoice DTO", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "amountSats" ], "properties": { "walletId": { "type": "string" }, "amountSats": { "type": "string" }, "memo": { "type": "string" }, "expiresInSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "invoice": { "type": "object", "required": [ "id", "provider", "walletId", "amountSats", "paymentRequest", "status", "createdAt", "expiresAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "walletId": { "type": "string" }, "amountSats": { "type": "string" }, "memo": { "type": "string" }, "paymentRequest": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "paid", "expired", "canceled" ] }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/spark/lightning/invoices/{invoiceId}": { "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Get a Lightning invoice DTO", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "invoice": { "type": "object", "required": [ "id", "provider", "walletId", "amountSats", "paymentRequest", "status", "createdAt", "expiresAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "walletId": { "type": "string" }, "amountSats": { "type": "string" }, "memo": { "type": "string" }, "paymentRequest": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "paid", "expired", "canceled" ] }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/adapters/spark/lightning/pay": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned Lightning payment intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "paymentRequest" ], "properties": { "agentId": { "type": "string" }, "walletId": { "type": "string" }, "paymentRequest": { "type": "string" }, "maxFeeSats": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/spark/transfers": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned Spark BTC transfer intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "recipient", "amountSats" ], "properties": { "agentId": { "type": "string" }, "walletId": { "type": "string" }, "recipient": { "type": "string" }, "amountSats": { "type": "string" }, "memo": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/spark/token-transfers": { "post": { "tags": [ "Adapters" ], "summary": "Build an unsigned Spark token transfer intent after policy/spend checks", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "recipient", "tokenId", "amount" ], "properties": { "agentId": { "type": "string" }, "walletId": { "type": "string" }, "recipient": { "type": "string" }, "tokenId": { "type": "string" }, "amount": { "type": "string" }, "memo": { "type": "string" }, "estimatedUsd": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "unsignedIntent": { "type": "object", "required": [ "signed", "kind", "chainId", "to", "value", "owner", "category", "provider" ], "properties": { "signed": { "type": "boolean", "const": false }, "kind": { "type": "string", "enum": [ "evm-tx", "evm-typed-data", "abstract-intent" ] }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "owner": { "type": "string" }, "category": { "type": "string" }, "provider": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/spark/identity/sign": { "post": { "tags": [ "Adapters" ], "summary": "Request Spark identity-key signing", "description": "The mock Spark adapter fails closed with 501 and never fabricates signatures. A real provider must be configured before this can return a signature.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "payload" ], "properties": { "walletId": { "type": "string" }, "payload": { "type": "string" } } } } } }, "responses": { "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "501": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/exchange/sessions": { "post": { "tags": [ "Adapters" ], "summary": "Create an exchange embed session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "returnUrl" ], "properties": { "userId": { "type": "string" }, "provider": { "type": "string", "enum": [ "kraken", "coinbase", "binance", "mock" ] }, "returnUrl": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "locale": { "type": "string" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "session": { "type": "object", "required": [ "id", "provider", "userId", "tenantId", "status", "url" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "tenantId": { "type": "string" }, "status": { "type": "string" }, "url": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/adapters/exchange/sessions/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Adapters" ], "summary": "Get an exchange embed session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "session": { "type": "object", "required": [ "id", "provider", "userId", "tenantId", "status", "url" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "tenantId": { "type": "string" }, "status": { "type": "string" }, "url": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/adapters/exchange/accounts": { "get": { "tags": [ "Adapters" ], "summary": "List linked exchange accounts", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "required": [ "id", "provider", "userId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "externalAccountId": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "integer" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/adapters/exchange/accounts/{accountId}": { "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Adapters" ], "summary": "Revoke a linked exchange account", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "account": { "type": "object", "required": [ "id", "provider", "userId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "externalAccountId": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/adapters", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/apps/{appId}/fiat": { "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Fiat" ], "summary": "Configure app-level fiat provider settings", "description": "Privy-compatible route placeholder. Steward exposes the OSS route surface but fails closed until a real fiat provider integration is configured.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "501": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/users/{userId}/fiat/accounts": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "description": "Tenant user id. Tenant-authenticated callers may act only for users in their tenant." } } ], "get": { "tags": [ "Fiat" ], "summary": "List a user's fiat accounts", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "required": [ "id", "provider", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "fiatCurrency": { "type": "string" }, "createdAt": { "type": "integer" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Fiat" ], "summary": "Create a user's fiat account", "description": "Fails closed with 501 unless a real banking/onramp provider is configured.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "501": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/users", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/users/{userId}/fiat/kyc_link": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "description": "Tenant user id. Tenant-authenticated callers may act only for users in their tenant." } } ], "post": { "tags": [ "Fiat" ], "summary": "Create a KYC link for a user", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "level" ], "properties": { "level": { "type": "string", "enum": [ "basic", "standard", "enhanced" ] }, "returnUrl": { "type": "string", "format": "uri" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "verification": { "type": "object", "required": [ "id", "provider", "userId", "level", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "level": { "type": "string", "enum": [ "basic", "standard", "enhanced" ] }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "rejected" ] }, "documents": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } } }, "kycLink": { "type": "string" }, "kyc_link": { "type": "string" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/users", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/users/{userId}/fiat/kyc": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "description": "Tenant user id. Tenant-authenticated callers may act only for users in their tenant." } } ], "get": { "tags": [ "Fiat" ], "summary": "Get fiat KYC status", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "verificationId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "status": { "type": "string" }, "verification": { "type": "object", "required": [ "id", "provider", "userId", "level", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "level": { "type": "string", "enum": [ "basic", "standard", "enhanced" ] }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "rejected" ] }, "documents": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Fiat" ], "summary": "Start fiat KYC verification", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "level" ], "properties": { "level": { "type": "string", "enum": [ "basic", "standard", "enhanced" ] }, "returnUrl": { "type": "string", "format": "uri" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "status": { "type": "string" }, "verification": { "type": "object", "required": [ "id", "provider", "userId", "level", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "level": { "type": "string", "enum": [ "basic", "standard", "enhanced" ] }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "rejected" ] }, "documents": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/users", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "patch": { "tags": [ "Fiat" ], "summary": "Submit fiat KYC document bytes", "description": "Raw document bytes are accepted only as request input, then hashed and discarded by the adapter. Responses and audit metadata expose only the hash and non-secret descriptors.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "verificationId", "documentType", "contentBase64" ], "properties": { "verificationId": { "type": "string" }, "documentType": { "type": "string" }, "contentBase64": { "type": "string", "description": "Base64 document bytes. The adapter hashes and discards raw bytes; responses and audits expose only non-secret document descriptors." } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "status": { "type": "string" }, "verification": { "type": "object", "required": [ "id", "provider", "userId", "level", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "userId": { "type": "string" }, "level": { "type": "string", "enum": [ "basic", "standard", "enhanced" ] }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "rejected" ] }, "documents": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/users", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/users/{userId}/fiat/onramp": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "description": "Tenant user id. Tenant-authenticated callers may act only for users in their tenant." } } ], "post": { "tags": [ "Fiat" ], "summary": "Create a fiat onramp session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fiatCurrency", "fiatAmount", "cryptoAsset", "chainId", "destinationAddress" ], "properties": { "fiatCurrency": { "type": "string" }, "fiatAmount": { "type": "number", "minimum": 0 }, "cryptoAsset": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 }, "destinationAddress": { "type": "string" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quote": { "type": "object", "additionalProperties": true }, "session": { "type": "object", "required": [ "id", "provider", "tenantId", "userId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "tenantId": { "type": "string" }, "userId": { "type": "string" }, "status": { "type": "string" }, "fiatCurrency": { "type": "string" }, "fiatAmount": { "type": "number" }, "cryptoAsset": { "type": "string" }, "chainId": { "type": "integer" }, "cryptoAmount": { "type": "string" }, "destinationAddress": { "type": "string" }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/users", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/users/{userId}/fiat/onramp/{sessionId}": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "description": "Tenant user id. Tenant-authenticated callers may act only for users in their tenant." } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Fiat" ], "summary": "Get a fiat onramp session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "session": { "type": "object", "required": [ "id", "provider", "tenantId", "userId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "tenantId": { "type": "string" }, "userId": { "type": "string" }, "status": { "type": "string" }, "fiatCurrency": { "type": "string" }, "fiatAmount": { "type": "number" }, "cryptoAsset": { "type": "string" }, "chainId": { "type": "integer" }, "cryptoAmount": { "type": "string" }, "destinationAddress": { "type": "string" }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/users/{userId}/fiat/offramp": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "description": "Tenant user id. Tenant-authenticated callers may act only for users in their tenant." } } ], "post": { "tags": [ "Fiat" ], "summary": "Create a fiat offramp session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cryptoAsset", "cryptoAmount", "chainId", "fiatCurrency", "payoutMethodId" ], "properties": { "cryptoAsset": { "type": "string" }, "cryptoAmount": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 }, "fiatCurrency": { "type": "string" }, "payoutMethodId": { "type": "string" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quote": { "type": "object", "additionalProperties": true }, "session": { "type": "object", "required": [ "id", "provider", "tenantId", "userId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "tenantId": { "type": "string" }, "userId": { "type": "string" }, "status": { "type": "string" }, "cryptoAsset": { "type": "string" }, "cryptoAmount": { "type": "string" }, "chainId": { "type": "integer" }, "fiatCurrency": { "type": "string" }, "fiatAmount": { "type": "number" }, "depositAddress": { "type": "string" }, "payoutMethodId": { "type": "string" }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/users", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/users/{userId}/fiat/offramp/{sessionId}": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "description": "Tenant user id. Tenant-authenticated callers may act only for users in their tenant." } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Fiat" ], "summary": "Get a fiat offramp session", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "session": { "type": "object", "required": [ "id", "provider", "tenantId", "userId", "status" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "tenantId": { "type": "string" }, "userId": { "type": "string" }, "status": { "type": "string" }, "cryptoAsset": { "type": "string" }, "cryptoAmount": { "type": "string" }, "chainId": { "type": "integer" }, "fiatCurrency": { "type": "string" }, "fiatAmount": { "type": "number" }, "depositAddress": { "type": "string" }, "payoutMethodId": { "type": "string" }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/audit/log": { "get": { "tags": [ "Audits" ], "summary": "List tenant transaction and proxy audit log entries", "description": "Requires an owner/admin browser session with recent MFA. Returns tenant-scoped, no-store audit data; agent tokens and tenant API keys are not sufficient. Supports agent, action, status, date range, and page/limit filters across transaction approvals/signatures plus proxy audit rows.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sign", "approve", "reject", "proxy" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "timestamp", "agentId", "action", "status", "details" ], "properties": { "id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "agentId": { "type": "string" }, "action": { "type": "string", "enum": [ "sign", "approve", "reject", "proxy" ] }, "status": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "policyResults": {}, "value": { "type": "string" }, "to": { "type": "string" } } } }, "pagination": { "type": "object", "required": [ "page", "limit", "total", "totalPages" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "total": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/audit/summary": { "get": { "tags": [ "Audits" ], "summary": "Summarize tenant audit activity", "description": "Requires an owner/admin browser session with recent MFA. Returns tenant-scoped, no-store audit data; agent tokens and tenant API keys are not sufficient. Summarizes transaction, approval, rejection, proxy, policy-violation, top-agent, and daily activity counts for 24h, 7d, 30d, or all when explicitly enabled by server configuration.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "all" ], "default": "30d" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "totalTransactions", "totalApprovals", "totalRejections", "totalProxyRequests", "policyViolations", "topAgents", "dailyActivity" ], "properties": { "totalTransactions": { "type": "integer", "minimum": 0 }, "totalApprovals": { "type": "integer", "minimum": 0 }, "totalRejections": { "type": "integer", "minimum": 0 }, "totalProxyRequests": { "type": "integer", "minimum": 0 }, "policyViolations": { "type": "integer", "minimum": 0 }, "topAgents": { "type": "array", "items": { "type": "object", "required": [ "agentId", "name", "txCount" ], "properties": { "agentId": { "type": "string" }, "name": { "type": "string" }, "txCount": { "type": "integer", "minimum": 0 } } } }, "dailyActivity": { "type": "array", "items": { "type": "object", "required": [ "date", "txCount" ], "properties": { "date": { "type": "string", "format": "date" }, "txCount": { "type": "integer", "minimum": 0 } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/audit/export": { "get": { "tags": [ "Audits" ], "summary": "Export tenant audit log rows as CSV", "description": "Requires an owner/admin browser session with recent MFA. Returns tenant-scoped, no-store audit data; agent tokens and tenant API keys are not sufficient. Requires dateFrom and dateTo and rejects ranges over 31 days. The CSV columns are id,timestamp,agentId,action,status,to,value,details.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sign", "approve", "reject", "proxy" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "dateFrom", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "dateTo", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "CSV audit export", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/audit/events": { "get": { "tags": [ "Audits" ], "summary": "List tenant audit events", "description": "Requires an owner/admin browser session with recent MFA. Supports exact action filters, action-prefix filters for wallet/action history views, exact actor/resource/request filters, date ranges, pagination, and up to five exact metadata filters using dot-path query keys such as `metadata.adapter.kind=swap`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,128}$" } }, { "name": "actionPrefix", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,128}$" } }, { "name": "actorType", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "actorId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "resourceType", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "resourceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "requestId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "metadata.", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact metadata filter. Replace with a dot-separated JSON metadata path, for example metadata.adapter.kind=swap. Up to five filters are accepted." } }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "seq", "actor_type", "actor_id", "action", "resource_type", "resource_id", "metadata", "created_at" ], "properties": { "id": { "type": "string" }, "seq": { "type": "integer", "minimum": 1 }, "actor_type": { "type": [ "string", "null" ] }, "actor_id": { "type": [ "string", "null" ] }, "action": { "type": "string" }, "resource_type": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "ip_address": { "type": [ "string", "null" ] }, "user_agent": { "type": [ "string", "null" ] }, "request_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "type": "object", "required": [ "page", "limit", "total", "totalPages" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "total": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/audit/verify": { "post": { "tags": [ "Audits" ], "summary": "Verify tenant audit chain integrity", "description": "Requires an owner/admin browser session with recent MFA. Returns tenant-scoped, no-store audit data; agent tokens and tenant API keys are not sufficient. Walks the tenant audit chain and verifies HMAC continuity over at most 10,000 rows. Partial verification starts at fromSeq and is anchored to the stored predecessor hash; use requireHead=true to require the current chain head.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "fromSeq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "toSeq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "requireHead", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "valid", "anchored", "requireHead", "verifiedFromSeq", "verifiedToSeq" ], "anyOf": [ { "required": [ "valid", "count" ] }, { "required": [ "valid", "brokenAt" ] } ], "properties": { "valid": { "type": "boolean" }, "count": { "type": "integer", "minimum": 0 }, "brokenAt": { "type": "integer", "minimum": 1 }, "anchored": { "type": "boolean" }, "requireHead": { "type": "boolean" }, "verifiedFromSeq": { "type": "integer", "minimum": 1 }, "verifiedToSeq": { "type": "integer", "minimum": 0 }, "warning": { "type": "string" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/audit", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/audit/integrity": { "get": { "tags": [ "Audits" ], "summary": "Verify audit chain and latest checkpoint at the current head", "description": "Requires an owner/admin browser session with recent MFA. Used by steward doctor to verify the live HMAC chain and the newest persisted Ed25519 checkpoint without returning signing or HMAC key material.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid", "chainValid", "checkpointPresent", "checkpointValid", "checkpointAtHead", "checkpointSeq", "chainHeadSeq", "governedRoutes" ], "properties": { "valid": { "type": "boolean" }, "chainValid": { "type": "boolean" }, "checkpointPresent": { "type": "boolean" }, "checkpointValid": { "type": "boolean" }, "checkpointAtHead": { "type": "boolean" }, "checkpointSeq": { "type": [ "integer", "null" ] }, "chainHeadSeq": { "type": [ "integer", "null" ] }, "governedRoutes": { "type": "object", "required": [ "governedRoutes", "nullOperationRoutes", "dualModeRoutes", "ok" ], "properties": { "governedRoutes": { "type": "integer" }, "nullOperationRoutes": { "type": "integer" }, "dualModeRoutes": { "type": "integer" }, "ok": { "type": "boolean" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/secrets": { "get": { "tags": [ "Secrets" ], "summary": "List tenant secret metadata", "description": "Requires an owner/admin browser session with recent MFA. Returns metadata only; secret values are never included in responses. Tenant API keys and agent tokens cannot read this inventory.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "name", "version", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": "integer", "minimum": 1 }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Secrets" ], "summary": "Create a tenant secret", "description": "Requires an owner/admin browser session with recent MFA. Secret values are accepted only for create/rotate requests, never returned, and sensitive route hardening headers are advertised for mutation calls.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string", "description": "Secret value. Values are accepted for create/rotate only and never returned." }, "description": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "version", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": "integer", "minimum": 1 }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/secrets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/secrets/routes": { "get": { "tags": [ "Secrets" ], "summary": "List credential injection routes", "description": "Requires an owner/admin browser session with recent MFA. Returns metadata only; secret values are never included in responses. Tenant API keys and agent tokens cannot read this inventory. Credential injection routes bind a secret to one tenant agent and an explicit allowlisted upstream host/path/method/header. Broad host, path, method, internal-host, line-break, and unsafe header injection patterns are rejected by the API.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "secretId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "agentId", "secretId", "hostPattern", "pathPattern", "method", "injectAs", "injectKey", "injectionStrategy", "injectionConfig", "enabled" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "secretId": { "type": "string" }, "hostPattern": { "type": "string" }, "pathPattern": { "type": "string" }, "method": { "type": "string", "enum": [ "*", "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "injectAs": { "type": "string", "enum": [ "header" ] }, "injectKey": { "type": "string" }, "injectFormat": { "type": [ "string", "null" ] }, "injectionStrategy": { "type": "string", "enum": [ "header", "sigv4" ] }, "injectionConfig": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "ec2" ] }, "region": { "type": "string" } }, "additionalProperties": false }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Secrets" ], "summary": "Create a credential injection route", "description": "Requires an owner/admin browser session with recent MFA. Secret values are accepted only for create/rotate requests, never returned, and sensitive route hardening headers are advertised for mutation calls. Credential injection routes bind a secret to one tenant agent and an explicit allowlisted upstream host/path/method/header. Broad host, path, method, internal-host, line-break, and unsafe header injection patterns are rejected by the API.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "hostPattern": { "type": "string" }, "pathPattern": { "type": "string" }, "method": { "type": "string", "enum": [ "*", "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "injectAs": { "type": "string", "enum": [ "header" ] }, "injectKey": { "type": "string" }, "injectFormat": { "type": "string" }, "injectionStrategy": { "type": "string", "enum": [ "header", "sigv4" ] }, "injectionConfig": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "ec2" ] }, "region": { "type": "string" } }, "additionalProperties": false }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "enabled": { "type": "boolean" }, "secretId": { "type": "string" } }, "required": [ "secretId", "agentId", "hostPattern", "injectAs", "injectKey" ] } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "secretId", "hostPattern", "pathPattern", "method", "injectAs", "injectKey", "injectionStrategy", "injectionConfig", "enabled" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "secretId": { "type": "string" }, "hostPattern": { "type": "string" }, "pathPattern": { "type": "string" }, "method": { "type": "string", "enum": [ "*", "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "injectAs": { "type": "string", "enum": [ "header" ] }, "injectKey": { "type": "string" }, "injectFormat": { "type": [ "string", "null" ] }, "injectionStrategy": { "type": "string", "enum": [ "header", "sigv4" ] }, "injectionConfig": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "ec2" ] }, "region": { "type": "string" } }, "additionalProperties": false }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/secrets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/secrets/routes/{routeId}": { "parameters": [ { "name": "routeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "tags": [ "Secrets" ], "summary": "Update a credential injection route", "description": "Requires an owner/admin browser session with recent MFA. Secret values are accepted only for create/rotate requests, never returned, and sensitive route hardening headers are advertised for mutation calls. Credential injection routes bind a secret to one tenant agent and an explicit allowlisted upstream host/path/method/header. Broad host, path, method, internal-host, line-break, and unsafe header injection patterns are rejected by the API.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "hostPattern": { "type": "string" }, "pathPattern": { "type": "string" }, "method": { "type": "string", "enum": [ "*", "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "injectAs": { "type": "string", "enum": [ "header" ] }, "injectKey": { "type": "string" }, "injectFormat": { "type": "string" }, "injectionStrategy": { "type": "string", "enum": [ "header", "sigv4" ] }, "injectionConfig": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "ec2" ] }, "region": { "type": "string" } }, "additionalProperties": false }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "agentId", "secretId", "hostPattern", "pathPattern", "method", "injectAs", "injectKey", "injectionStrategy", "injectionConfig", "enabled" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "secretId": { "type": "string" }, "hostPattern": { "type": "string" }, "pathPattern": { "type": "string" }, "method": { "type": "string", "enum": [ "*", "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "injectAs": { "type": "string", "enum": [ "header" ] }, "injectKey": { "type": "string" }, "injectFormat": { "type": [ "string", "null" ] }, "injectionStrategy": { "type": "string", "enum": [ "header", "sigv4" ] }, "injectionConfig": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "ec2" ] }, "region": { "type": "string" } }, "additionalProperties": false }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/secrets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Secrets" ], "summary": "Delete a credential injection route", "description": "Requires an owner/admin browser session with recent MFA. Secret values are accepted only for create/rotate requests, never returned, and sensitive route hardening headers are advertised for mutation calls.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deleted": { "type": "string" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/secrets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/secrets/{secretId}": { "parameters": [ { "name": "secretId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Secrets" ], "summary": "Get tenant secret metadata", "description": "Requires an owner/admin browser session with recent MFA. Returns metadata only; secret values are never included in responses. Tenant API keys and agent tokens cannot read this inventory.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "version", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": "integer", "minimum": 1 }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "put": { "tags": [ "Secrets" ], "summary": "Rotate a tenant secret value", "description": "Requires an owner/admin browser session with recent MFA. Secret values are accepted only for create/rotate requests, never returned, and sensitive route hardening headers are advertised for mutation calls.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "Replacement secret value. Values are accepted for rotate only and never returned." } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "version", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": "integer", "minimum": 1 }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/secrets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Secrets" ], "summary": "Delete a tenant secret", "description": "Requires an owner/admin browser session with recent MFA. Secret values are accepted only for create/rotate requests, never returned, and sensitive route hardening headers are advertised for mutation calls.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deleted": { "type": "string" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/secrets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/secrets/{secretId}/rotate": { "parameters": [ { "name": "secretId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Secrets" ], "summary": "Rotate a tenant secret value", "description": "Requires an owner/admin browser session with recent MFA. Secret values are accepted only for create/rotate requests, never returned, and sensitive route hardening headers are advertised for mutation calls.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "Replacement secret value. Values are accepted for rotate only and never returned." } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "name", "version", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": "integer", "minimum": 1 }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/secrets", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook configurations", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot manage webhook configuration or delivery controls. Responses redact webhook secrets, payloads, webhook URLs in delivery rows, and raw provider error text except for the one-time secret returned by create.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "url", "events", "enabled", "maxRetries", "retryBackoffMs", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "tx.pending", "tx.approved", "tx.denied", "tx.signed", "spend.threshold", "policy.violation", "wallet_action.transfer.failed", "wallet_action.transfer.succeeded", "wallet_action.send_calls.failed", "wallet_action.send_calls.succeeded", "wallet.raw_signature.created", "wallet.private_key_exported", "user.wallet.created", "intent.created", "intent.authorized", "intent.executed", "intent.failed", "intent.rejected", "intent.canceled", "intent.expired" ] } }, "enabled": { "type": "boolean" }, "maxRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryBackoffMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }, "description": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook configuration", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot manage webhook configuration or delivery controls. Returns the webhook signing secret exactly once in the create response.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "tx.pending", "tx.approved", "tx.denied", "tx.signed", "spend.threshold", "policy.violation", "wallet_action.transfer.failed", "wallet_action.transfer.succeeded", "wallet_action.send_calls.failed", "wallet_action.send_calls.succeeded", "wallet.raw_signature.created", "wallet.private_key_exported", "user.wallet.created", "intent.created", "intent.authorized", "intent.executed", "intent.failed", "intent.rejected", "intent.canceled", "intent.expired" ] } }, "enabled": { "type": "boolean" }, "description": { "type": "string" }, "maxRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryBackoffMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "url", "events", "enabled", "maxRetries", "retryBackoffMs", "createdAt", "secret" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "tx.pending", "tx.approved", "tx.denied", "tx.signed", "spend.threshold", "policy.violation", "wallet_action.transfer.failed", "wallet_action.transfer.succeeded", "wallet_action.send_calls.failed", "wallet_action.send_calls.succeeded", "wallet.raw_signature.created", "wallet.private_key_exported", "user.wallet.created", "intent.created", "intent.authorized", "intent.executed", "intent.failed", "intent.rejected", "intent.canceled", "intent.expired" ] } }, "enabled": { "type": "boolean" }, "maxRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryBackoffMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }, "description": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "One-time webhook signing secret. Returned only from create responses." } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/webhooks", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/webhooks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "tags": [ "Webhooks" ], "summary": "Update a webhook configuration", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot manage webhook configuration or delivery controls. Responses redact webhook secrets, payloads, webhook URLs in delivery rows, and raw provider error text except for the one-time secret returned by create.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "tx.pending", "tx.approved", "tx.denied", "tx.signed", "spend.threshold", "policy.violation", "wallet_action.transfer.failed", "wallet_action.transfer.succeeded", "wallet_action.send_calls.failed", "wallet_action.send_calls.succeeded", "wallet.raw_signature.created", "wallet.private_key_exported", "user.wallet.created", "intent.created", "intent.authorized", "intent.executed", "intent.failed", "intent.rejected", "intent.canceled", "intent.expired" ] } }, "enabled": { "type": "boolean" }, "description": { "type": "string" }, "maxRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryBackoffMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "tenantId", "url", "events", "enabled", "maxRetries", "retryBackoffMs", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "tx.pending", "tx.approved", "tx.denied", "tx.signed", "spend.threshold", "policy.violation", "wallet_action.transfer.failed", "wallet_action.transfer.succeeded", "wallet_action.send_calls.failed", "wallet_action.send_calls.succeeded", "wallet.raw_signature.created", "wallet.private_key_exported", "user.wallet.created", "intent.created", "intent.authorized", "intent.executed", "intent.failed", "intent.rejected", "intent.canceled", "intent.expired" ] } }, "enabled": { "type": "boolean" }, "maxRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryBackoffMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }, "description": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/webhooks", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook configuration", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot manage webhook configuration or delivery controls.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "const": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/webhooks", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/webhooks/{id}/test": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Webhooks" ], "summary": "Send a diagnostic webhook test delivery", "description": "Requires owner/admin session with recent MFA. Sends a signed webhook.test diagnostic delivery to an enabled endpoint; webhook.test is not a subscribable event type.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "eventType", "status" ], "properties": { "eventType": { "type": "string", "const": "webhook.test" }, "status": { "type": "string", "const": "delivered" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/webhooks", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/webhooks/{id}/deliveries": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Webhooks" ], "summary": "List redacted webhook delivery history", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot manage webhook configuration or delivery controls. Responses redact webhook secrets, payloads, webhook URLs in delivery rows, and raw provider error text except for the one-time secret returned by create.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100000 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed" ] } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "hasError", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "eventType", "status", "attempts", "maxAttempts", "hasError", "createdAt" ], "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed" ] }, "attempts": { "type": "integer", "minimum": 0 }, "maxAttempts": { "type": "integer", "minimum": 0 }, "nextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "replayedFromDeliveryId": { "type": [ "string", "null" ] }, "hasError": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/webhooks/{id}/deliveries/export": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Webhooks" ], "summary": "Export redacted webhook delivery history", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot manage webhook configuration or delivery controls. Returns the same redacted delivery fields as the JSON history endpoint for offline review.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100000 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed" ] } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "hasError", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "webhookId", "exportedAt", "deliveries" ], "properties": { "webhookId": { "type": "string" }, "exportedAt": { "type": "string", "format": "date-time" }, "deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "eventType", "status", "attempts", "maxAttempts", "hasError", "createdAt" ], "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed" ] }, "attempts": { "type": "integer", "minimum": 0 }, "maxAttempts": { "type": "integer", "minimum": 0 }, "nextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "replayedFromDeliveryId": { "type": [ "string", "null" ] }, "hasError": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/webhooks/deliveries/{id}/retry": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Webhooks" ], "summary": "Retry a failed webhook delivery", "description": "Requires owner/admin session with recent MFA. Re-queues an eligible failed delivery without resetting attempts or bypassing the configured retry budget.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "eventType", "status", "attempts", "maxAttempts", "hasError", "createdAt" ], "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed" ] }, "attempts": { "type": "integer", "minimum": 0 }, "maxAttempts": { "type": "integer", "minimum": 0 }, "nextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "replayedFromDeliveryId": { "type": [ "string", "null" ] }, "hasError": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/webhooks", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/webhooks/deliveries/{id}/replay": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Webhooks" ], "summary": "Replay a historical webhook delivery", "description": "Requires owner/admin session with recent MFA. Creates a new signed delivery with a new delivery ID when the original webhook still exists, is enabled, has the same URL, and still subscribes to the event type.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "eventType", "status", "attempts", "maxAttempts", "hasError", "createdAt" ], "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed" ] }, "attempts": { "type": "integer", "minimum": 0 }, "maxAttempts": { "type": "integer", "minimum": 0 }, "nextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "replayedFromDeliveryId": { "type": [ "string", "null" ] }, "hasError": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/webhooks", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/approvals": { "get": { "tags": [ "Approvals" ], "summary": "List manual approval queue entries", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot review or mutate manual approvals. Supports status and tenant-scoped agent filters before stable (requestedAt, id) keyset pagination.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "all" ] } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000 } }, { "name": "cursorRequestedAt", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "cursorId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "txId", "agentId", "status", "requestedAt" ], "properties": { "id": { "type": "string" }, "txId": { "type": "string" }, "agentId": { "type": "string" }, "agentName": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resolvedBy": { "type": [ "string", "null" ] }, "toAddress": { "type": [ "string", "null" ] }, "value": { "type": [ "string", "null" ] }, "chainId": { "type": [ "integer", "null" ] }, "txStatus": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": true } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/approvals/stats": { "get": { "tags": [ "Approvals" ], "summary": "Get manual approval queue statistics", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot review or mutate manual approvals.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "pending", "approved", "rejected", "total", "avgWaitSeconds" ], "properties": { "pending": { "type": "integer", "minimum": 0 }, "approved": { "type": "integer", "minimum": 0 }, "rejected": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "avgWaitSeconds": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/approvals/{txId}/approve": { "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Approvals" ], "summary": "Approve a non-vault manual approval entry", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot review or mutate manual approvals. This generic approval route does not execute vault transactions; executable vault approvals must use POST /vault/{agentId}/approve/{txId} so signing, policy revalidation, audit rollback, and broadcast semantics stay on the vault path.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 1000 }, "approvedBy": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "txId", "agentId", "status", "requestedAt" ], "properties": { "id": { "type": "string" }, "txId": { "type": "string" }, "agentId": { "type": "string" }, "agentName": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resolvedBy": { "type": [ "string", "null" ] }, "toAddress": { "type": [ "string", "null" ] }, "value": { "type": [ "string", "null" ] }, "chainId": { "type": [ "integer", "null" ] }, "txStatus": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/approvals", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/approvals/{txId}/deny": { "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Approvals" ], "summary": "Deny a manual approval entry", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot review or mutate manual approvals. Denial updates the approval and transaction status in one transaction, writes audit events, and dispatches denial webhooks.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000 }, "deniedBy": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "txId", "agentId", "status", "requestedAt" ], "properties": { "id": { "type": "string" }, "txId": { "type": "string" }, "agentId": { "type": "string" }, "agentName": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resolvedBy": { "type": [ "string", "null" ] }, "toAddress": { "type": [ "string", "null" ] }, "value": { "type": [ "string", "null" ] }, "chainId": { "type": [ "integer", "null" ] }, "txStatus": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/approvals", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/approvals/rules": { "get": { "tags": [ "Approvals" ], "summary": "Get tenant auto-approval rules", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot review or mutate manual approvals.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "anyOf": [ { "type": "object", "required": [ "tenantId", "maxAmountWei", "enabled" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "maxAmountWei": { "type": "string", "pattern": "^\\d+$" }, "autoDenyAfterHours": { "type": [ "number", "null" ], "exclusiveMinimum": 0 }, "escalateAboveWei": { "type": [ "string", "null" ], "pattern": "^\\d+$" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, { "type": "null" } ] } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "put": { "tags": [ "Approvals" ], "summary": "Create or update tenant auto-approval rules", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot review or mutate manual approvals. Rule writes are audited before persistence and rolled back if the final audit write fails.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxAmountWei": { "type": "string", "pattern": "^\\d+$" }, "autoDenyAfterHours": { "type": [ "number", "null" ], "exclusiveMinimum": 0 }, "escalateAboveWei": { "type": [ "string", "null" ], "pattern": "^\\d+$" }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "tenantId", "maxAmountWei", "enabled" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "maxAmountWei": { "type": "string", "pattern": "^\\d+$" }, "autoDenyAfterHours": { "type": [ "number", "null" ], "exclusiveMinimum": 0 }, "escalateAboveWei": { "type": [ "string", "null" ], "pattern": "^\\d+$" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "tenantId", "maxAmountWei", "enabled" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "maxAmountWei": { "type": "string", "pattern": "^\\d+$" }, "autoDenyAfterHours": { "type": [ "number", "null" ], "exclusiveMinimum": 0 }, "escalateAboveWei": { "type": [ "string", "null" ], "pattern": "^\\d+$" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/approvals", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/global-wallet/consent/request": { "get": { "tags": [ "Global Wallet" ], "summary": "Preview a global wallet consent request", "description": "Requires an authenticated user session. App access is bound to an enabled tenant app client, allowed Origin/Referer, allowed redirect URI, and selected wallet index; responses are no-store.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "app_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "appId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "origin", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "redirectUri", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "wallet_index", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "walletIndex", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "app", "requestedScopes", "wallet", "consent" ], "properties": { "app": { "type": "object", "required": [ "id", "appId", "tenantId", "name", "origin" ], "properties": { "id": { "type": "string" }, "appId": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "environment": { "type": "string" }, "origin": { "type": "string" }, "redirectUri": { "type": [ "string", "null" ] } } }, "requestedScopes": { "type": "array", "items": { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] } }, "wallet": { "type": "object", "required": [ "agentId", "address", "walletIndex" ], "properties": { "agentId": { "type": "string" }, "address": { "type": "string" }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 } } }, "consent": { "anyOf": [ { "type": "object", "required": [ "id", "tenantId", "clientId", "appId", "origin", "walletAgentId", "walletAddress", "scopes", "status" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "clientId": { "type": "string" }, "appId": { "type": "string" }, "origin": { "type": "string" }, "redirectUri": { "type": [ "string", "null" ] }, "walletAgentId": { "type": "string" }, "walletAddress": { "type": "string" }, "walletIndex": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 255 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] } }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "grantedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, { "type": "null" } ] } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/global-wallet/consent/approve": { "post": { "tags": [ "Global Wallet" ], "summary": "Approve global wallet app access", "description": "Requires an authenticated user session. App access is bound to an enabled tenant app client, allowed Origin/Referer, allowed redirect URI, and selected wallet index; responses are no-store. Requires recent MFA. Write-capable global-wallet methods also require active consent for the exact origin/app, selected wallet index, wallet binding, explicit server-side enablement where applicable, and a one-time action confirmation. Existing active consent for the same user/app/origin is revoked before the new consent is inserted, and approval is rolled back if the final audit write fails.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "app_id" ], "properties": { "app_id": { "type": "string" }, "appId": { "type": "string" }, "origin": { "type": "string" }, "redirect_uri": { "type": "string" }, "redirectUri": { "type": "string" }, "wallet_index": { "type": "integer", "minimum": 0, "maximum": 255 }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "scope": { "anyOf": [ { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] }, { "type": "array", "items": { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] } } ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] } } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "consent", "wallet" ], "properties": { "consent": { "type": "object", "required": [ "id", "tenantId", "clientId", "appId", "origin", "walletAgentId", "walletAddress", "scopes", "status" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "clientId": { "type": "string" }, "appId": { "type": "string" }, "origin": { "type": "string" }, "redirectUri": { "type": [ "string", "null" ] }, "walletAgentId": { "type": "string" }, "walletAddress": { "type": "string" }, "walletIndex": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 255 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] } }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "grantedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "wallet": { "type": "object", "required": [ "agentId", "address", "walletIndex" ], "properties": { "agentId": { "type": "string" }, "address": { "type": "string" }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/global-wallet", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/global-wallet/consents": { "get": { "tags": [ "Global Wallet" ], "summary": "List authenticated user's global wallet app consents", "description": "Requires an authenticated user session. App access is bound to an enabled tenant app client, allowed Origin/Referer, allowed redirect URI, and selected wallet index; responses are no-store.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "consents" ], "properties": { "consents": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "clientId", "appId", "origin", "walletAgentId", "walletAddress", "scopes", "status" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "clientId": { "type": "string" }, "appId": { "type": "string" }, "origin": { "type": "string" }, "redirectUri": { "type": [ "string", "null" ] }, "walletAgentId": { "type": "string" }, "walletAddress": { "type": "string" }, "walletIndex": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 255 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] } }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "grantedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/global-wallet/consents/{consentId}/revoke": { "parameters": [ { "name": "consentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Global Wallet" ], "summary": "Revoke global wallet app access", "description": "Requires recent MFA. Write-capable global-wallet methods also require active consent for the exact origin/app, selected wallet index, wallet binding, explicit server-side enablement where applicable, and a one-time action confirmation.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "consent" ], "properties": { "consent": { "type": "object", "required": [ "id", "tenantId", "clientId", "appId", "origin", "walletAgentId", "walletAddress", "scopes", "status" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "clientId": { "type": "string" }, "appId": { "type": "string" }, "origin": { "type": "string" }, "redirectUri": { "type": [ "string", "null" ] }, "walletAgentId": { "type": "string" }, "walletAddress": { "type": "string" }, "walletIndex": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 255 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] } }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "grantedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/global-wallet", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/global-wallet/rpc/confirm": { "post": { "tags": [ "Global Wallet" ], "summary": "Create a one-time global wallet action confirmation", "description": "Requires recent MFA. Write-capable global-wallet methods also require active consent for the exact origin/app, selected wallet index, wallet binding, explicit server-side enablement where applicable, and a one-time action confirmation. Confirmations are bound to consent, user, tenant app, origin, method, request hash, wallet agent id, wallet address, and wallet index and expire after five minutes.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "app_id", "method" ], "properties": { "app_id": { "type": "string" }, "appId": { "type": "string" }, "origin": { "type": "string" }, "method": { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] }, "params": {}, "wallet_index": { "type": "integer", "minimum": 0, "maximum": 255 }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "confirmation_id": { "type": "string" }, "confirmationId": { "type": "string" }, "id": {}, "jsonrpc": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "confirmationId", "method", "expiresAt" ], "properties": { "confirmationId": { "type": "string" }, "method": { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] }, "wallet": { "type": "object", "required": [ "agentId", "address", "walletIndex" ], "properties": { "agentId": { "type": "string" }, "address": { "type": "string" }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 } } }, "expiresAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/global-wallet", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/global-wallet/rpc/scan": { "post": { "tags": [ "Global Wallet" ], "summary": "Scan a global wallet transaction request", "description": "Requires active consent for eth_sendTransaction and the selected wallet index. Native-transfer-shaped requests produce risk and confirmation metadata; contract calldata is blocked until selector-aware scanning is configured.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "app_id", "method" ], "properties": { "app_id": { "type": "string" }, "appId": { "type": "string" }, "origin": { "type": "string" }, "method": { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] }, "params": {}, "wallet_index": { "type": "integer", "minimum": 0, "maximum": 255 }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "confirmation_id": { "type": "string" }, "confirmationId": { "type": "string" }, "id": {}, "jsonrpc": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "method", "wallet", "transaction", "blocked", "riskLevel", "warnings", "confirmationRequired", "executionSupported" ], "properties": { "method": { "type": "string", "const": "eth_sendTransaction" }, "wallet": { "type": "object", "required": [ "address", "agentId", "walletIndex" ], "properties": { "address": { "type": "string" }, "agentId": { "type": "string" }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 } } }, "transaction": { "type": "object", "required": [ "to", "valueWei", "chainId" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "valueWei": { "type": "string" }, "data": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 } } }, "blocked": { "type": "boolean" }, "riskLevel": { "type": "string", "enum": [ "low", "medium", "blocked" ] }, "warnings": { "type": "array", "items": { "type": "object", "required": [ "code", "severity", "message" ], "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warning", "error" ] }, "message": { "type": "string" } } } }, "confirmationRequired": { "type": "boolean", "const": true }, "executionSupported": { "type": "boolean" }, "unsupportedReason": { "type": [ "string", "null" ] } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/global-wallet", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/global-wallet/rpc": { "post": { "tags": [ "Global Wallet" ], "summary": "Call the global wallet RPC bridge", "description": "Read-only eth_accounts/eth_chainId are allowed by active consent. personal_sign, eth_signTypedData_v4, and eth_sendTransaction fail closed unless explicitly enabled by server flags, recent MFA, matching scope, selected wallet index, wallet binding, and one-time action confirmation. Contract calldata transactions are blocked until selector-aware scanning is configured.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "app_id", "method" ], "properties": { "app_id": { "type": "string" }, "appId": { "type": "string" }, "origin": { "type": "string" }, "method": { "type": "string", "enum": [ "eth_accounts", "personal_sign", "eth_signTypedData_v4", "eth_sendTransaction" ] }, "params": {}, "wallet_index": { "type": "integer", "minimum": 0, "maximum": 255 }, "walletIndex": { "type": "integer", "minimum": 0, "maximum": 255 }, "confirmation_id": { "type": "string" }, "confirmationId": { "type": "string" }, "id": {}, "jsonrpc": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "jsonrpc", "id", "result" ], "properties": { "jsonrpc": { "type": "string" }, "id": {}, "result": {} } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/global-wallet", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/trade/token-status": { "get": { "tags": [ "Trading" ], "summary": "Get last observed agent trade-token expiry", "description": "Tenant-authenticated diagnostic endpoint for observing agent JWT expiry without granting trading authority.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/TradeTokenStatus" } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/trade/sessions": { "post": { "tags": [ "Trading" ], "summary": "Create a policy-bounded Hyperliquid trading session", "description": "Creates a venue-scoped session after tenant authentication, agent-tenant ownership checks, optional agent-token scoping, wallet resolution, policy cap intersection, venue allowlist checks, and asset allowlist checks.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "venue" ], "properties": { "agentId": { "type": "string" }, "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "dailyCap": { "type": "number", "minimum": 0, "maximum": 50000, "default": 300 }, "perOrderCap": { "type": "number", "minimum": 0, "maximum": 10000, "default": 100 }, "leverageCap": { "type": "number", "minimum": 0, "maximum": 50, "default": 5 }, "allowedAssets": { "type": "array", "minItems": 1, "items": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] }, "default": [ "BTC", "ETH", "BNB" ] }, "ttlSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "default": 3600 } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "sessionId", "expiresAt" ], "properties": { "sessionId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/trade/sessions/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Trading" ], "summary": "Get a policy-bounded trading session", "description": "Tenant-authenticated session lookup. Agent-scoped callers can only access their own sessions.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "agentId", "tenantId", "venue", "walletId", "dailyCapUsd", "perOrderCapUsd", "leverageCap", "allowedAssets", "dailySpendUsd", "expiresAt", "remainingCapUsd" ], "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "tenantId": { "type": "string" }, "venue": { "type": "string", "const": "hyperliquid" }, "walletId": { "type": "string" }, "dailyCapUsd": { "type": "number", "minimum": 0 }, "perOrderCapUsd": { "type": "number", "minimum": 0 }, "leverageCap": { "type": "number", "minimum": 0 }, "allowedAssets": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] } }, "dailySpendUsd": { "type": "number", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "remainingCapUsd": { "type": "number", "minimum": 0 } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/trade/sessions/{id}/revoke": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Trading" ], "summary": "Revoke a trading session", "description": "Revokes a policy-bounded trading session and writes an audit event. Agent-scoped callers can only revoke their own sessions.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "sessionId", "revokedAt" ], "properties": { "sessionId": { "type": "string" }, "revokedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/trade/hyperliquid/order": { "post": { "tags": [ "Trading" ], "summary": "Submit a Hyperliquid order through an active agent session", "description": "Requires an agent JWT for the calling agent. Orders are rate-limited, idempotency-protected, scoped to an active Hyperliquid session, rechecked against adapter asset support, evaluated against leverage/per-order/daily-spend policy before signing, and audited on both success and policy rejection.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId", "side", "size" ], "properties": { "sessionId": { "type": "string" }, "coin": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] }, "asset": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "size": { "type": "number", "minimum": 0 }, "limitPx": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "limitPrice": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "leverage": { "type": "number", "minimum": 0, "default": 1 }, "reduceOnly": { "type": "boolean", "default": false }, "idempotencyKey": { "type": "string" } }, "anyOf": [ { "required": [ "coin" ] }, { "required": [ "asset" ] } ] } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "orderId", "status", "filledQty", "avgPrice", "txHash" ], "properties": { "orderId": { "type": "string" }, "status": { "type": "string" }, "filledQty": { "type": "number" }, "avgPrice": { "type": "number" }, "txHash": { "type": [ "string", "null" ] }, "builderPerp": { "type": "boolean" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/trade/{venue}/deposit": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Operator deposit recovery funds to a venue account", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Hyperliquid deposits sign a bounded Arbitrum native-USDC transfer from the agent's venue wallet to the Hyperliquid bridge; amount must be 5-2000 USDC with at most six decimals.", "security": [ { "platformKey": [] }, { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "amount" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "amount": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "bridge": { "type": "string" }, "amountUsdc": { "type": "number" }, "amountBaseUnits": { "type": "string" }, "txHash": { "type": "string" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/trade/{venue}/close-all": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Operator close all venue positions for an agent", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Every per-coin close result is audited so the recovery action remains traceable.", "security": [ { "platformKey": [] }, { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "closed": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/trade/{venue}/leverage": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Operator update Hyperliquid leverage for an agent position", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Builder-perp symbols such as xyz:SPCX are forced to isolated margin and capped at 3x before submitting Hyperliquid's separate updateLeverage action.", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "coin", "leverage" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "coin": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100 }, "isCross": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "coin": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] }, "leverage": { "type": "integer", "minimum": 1 }, "requestedLeverage": { "type": "integer", "minimum": 1 }, "isCross": { "type": "boolean" }, "builderPerp": { "type": "boolean" }, "result": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/trade/{venue}/usd-send": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Transfer internal USDC between Hyperliquid accounts", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Platform-key only route that submits Hyperliquid's user-signed usdSend action for internal USDC transfers between Hyperliquid accounts. The transfer is signed by the sending agent's master Hyperliquid wallet.", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "destination", "amount" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "destination": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "destination": { "type": "string" }, "amount": { "type": "string" }, "result": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/trade/{venue}/approve-builder": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Approve Hyperliquid builder-code fee cap for an agent", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Platform-key only route that submits Hyperliquid's user-signed approveBuilderFee action. The approval must be signed by the agent's master Hyperliquid wallet, not an API/agent wallet.", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "builder", "maxFeeRate" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "builder": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "maxFeeRate": { "type": "string", "examples": [ "0.1%" ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "builder": { "type": "string" }, "maxFeeRate": { "type": "string" }, "result": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/trade/{venue}/withdraw": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Operator withdraw venue funds for an agent", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Withdrawals must pass the approved-addresses policy gate before signing; if amount is omitted, the route reads the venue withdrawable balance and fails closed when unavailable.", "security": [ { "platformKey": [] }, { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "destination" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "destination": { "type": "string" }, "amount": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "destination": { "type": "string" }, "amount": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "result": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/trade/token-status": { "get": { "tags": [ "Trading" ], "summary": "Get last observed agent trade-token expiry", "description": "Tenant-authenticated diagnostic endpoint for observing agent JWT expiry without granting trading authority.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/TradeTokenStatus" } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/trade/sessions": { "post": { "tags": [ "Trading" ], "summary": "Create a policy-bounded Hyperliquid trading session", "description": "Creates a venue-scoped session after tenant authentication, agent-tenant ownership checks, optional agent-token scoping, wallet resolution, policy cap intersection, venue allowlist checks, and asset allowlist checks.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "venue" ], "properties": { "agentId": { "type": "string" }, "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "dailyCap": { "type": "number", "minimum": 0, "maximum": 50000, "default": 300 }, "perOrderCap": { "type": "number", "minimum": 0, "maximum": 10000, "default": 100 }, "leverageCap": { "type": "number", "minimum": 0, "maximum": 50, "default": 5 }, "allowedAssets": { "type": "array", "minItems": 1, "items": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] }, "default": [ "BTC", "ETH", "BNB" ] }, "ttlSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "default": 3600 } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "sessionId", "expiresAt" ], "properties": { "sessionId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/trade/sessions/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Trading" ], "summary": "Get a policy-bounded trading session", "description": "Tenant-authenticated session lookup. Agent-scoped callers can only access their own sessions.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "agentId", "tenantId", "venue", "walletId", "dailyCapUsd", "perOrderCapUsd", "leverageCap", "allowedAssets", "dailySpendUsd", "expiresAt", "remainingCapUsd" ], "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "tenantId": { "type": "string" }, "venue": { "type": "string", "const": "hyperliquid" }, "walletId": { "type": "string" }, "dailyCapUsd": { "type": "number", "minimum": 0 }, "perOrderCapUsd": { "type": "number", "minimum": 0 }, "leverageCap": { "type": "number", "minimum": 0 }, "allowedAssets": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] } }, "dailySpendUsd": { "type": "number", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "remainingCapUsd": { "type": "number", "minimum": 0 } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/v1/trade/sessions/{id}/revoke": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Trading" ], "summary": "Revoke a trading session", "description": "Revokes a policy-bounded trading session and writes an audit event. Agent-scoped callers can only revoke their own sessions.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "sessionId", "revokedAt" ], "properties": { "sessionId": { "type": "string" }, "revokedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/trade/hyperliquid/order": { "post": { "tags": [ "Trading" ], "summary": "Submit a Hyperliquid order through an active agent session", "description": "Requires an agent JWT for the calling agent. Orders are rate-limited, idempotency-protected, scoped to an active Hyperliquid session, rechecked against adapter asset support, evaluated against leverage/per-order/daily-spend policy before signing, and audited on both success and policy rejection.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId", "side", "size" ], "properties": { "sessionId": { "type": "string" }, "coin": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] }, "asset": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "size": { "type": "number", "minimum": 0 }, "limitPx": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "limitPrice": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "leverage": { "type": "number", "minimum": 0, "default": 1 }, "reduceOnly": { "type": "boolean", "default": false }, "idempotencyKey": { "type": "string" } }, "anyOf": [ { "required": [ "coin" ] }, { "required": [ "asset" ] } ] } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "orderId", "status", "filledQty", "avgPrice", "txHash" ], "properties": { "orderId": { "type": "string" }, "status": { "type": "string" }, "filledQty": { "type": "number" }, "avgPrice": { "type": "number" }, "txHash": { "type": [ "string", "null" ] }, "builderPerp": { "type": "boolean" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/trade/{venue}/deposit": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Operator deposit recovery funds to a venue account", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Hyperliquid deposits sign a bounded Arbitrum native-USDC transfer from the agent's venue wallet to the Hyperliquid bridge; amount must be 5-2000 USDC with at most six decimals.", "security": [ { "platformKey": [] }, { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "amount" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "amount": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "bridge": { "type": "string" }, "amountUsdc": { "type": "number" }, "amountBaseUnits": { "type": "string" }, "txHash": { "type": "string" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/trade/{venue}/close-all": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Operator close all venue positions for an agent", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Every per-coin close result is audited so the recovery action remains traceable.", "security": [ { "platformKey": [] }, { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "closed": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/trade/{venue}/leverage": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Operator update Hyperliquid leverage for an agent position", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Builder-perp symbols such as xyz:SPCX are forced to isolated margin and capped at 3x before submitting Hyperliquid's separate updateLeverage action.", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "coin", "leverage" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "coin": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100 }, "isCross": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "coin": { "anyOf": [ { "type": "string", "enum": [ "BTC", "ETH", "BNB", "SOL", "AVAX", "ARB", "OP", "NEAR", "HYPE", "ZEC", "XMR" ] }, { "type": "string", "pattern": "^[a-z0-9]+:[A-Z0-9]+$", "examples": [ "xyz:SPCX" ] } ] }, "leverage": { "type": "integer", "minimum": 1 }, "requestedLeverage": { "type": "integer", "minimum": 1 }, "isCross": { "type": "boolean" }, "builderPerp": { "type": "boolean" }, "result": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/trade/{venue}/usd-send": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Transfer internal USDC between Hyperliquid accounts", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Platform-key only route that submits Hyperliquid's user-signed usdSend action for internal USDC transfers between Hyperliquid accounts. The transfer is signed by the sending agent's master Hyperliquid wallet.", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "destination", "amount" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "destination": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "destination": { "type": "string" }, "amount": { "type": "string" }, "result": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/trade/{venue}/approve-builder": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Approve Hyperliquid builder-code fee cap for an agent", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Platform-key only route that submits Hyperliquid's user-signed approveBuilderFee action. The approval must be signed by the agent's master Hyperliquid wallet, not an API/agent wallet.", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "builder", "maxFeeRate" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "builder": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "maxFeeRate": { "type": "string", "examples": [ "0.1%" ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "builder": { "type": "string" }, "maxFeeRate": { "type": "string" }, "result": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/v1/trade/{venue}/withdraw": { "parameters": [ { "name": "venue", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hyperliquid" ] } } ], "post": { "tags": [ "Trading" ], "summary": "Operator withdraw venue funds for an agent", "description": "Operator recovery endpoint. Auth deliberately accepts platform operators or tenant admins and must not require an agent JWT, so humans can recover funds when the agent token is expired. Raw signing keys never leave the vault; all recovery actions are audited and idempotency-protected. Withdrawals must pass the approved-addresses policy gate before signing; if amount is omitted, the route reads the venue withdrawable balance and fails closed when unavailable.", "security": [ { "platformKey": [] }, { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId", "destination" ], "properties": { "agentId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "destination": { "type": "string" }, "amount": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "venue": { "type": "string", "const": "hyperliquid" }, "walletAddress": { "type": "string" }, "destination": { "type": "string" }, "amount": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "result": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/v1/trade", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/tenants/config": { "get": { "tags": [ "Tenant Config" ], "summary": "Get default public tenant config", "description": "Public discovery endpoint used by SDKs before sign-in. Returns redacted default tenant config and never reads tenant PII.", "security": [], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "tenantId" ], "properties": { "tenantId": { "type": "string" }, "displayName": { "type": "string" }, "policyExposure": { "type": "object", "additionalProperties": true }, "policyTemplates": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "secretRoutePresets": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "approvalConfig": { "type": "object", "additionalProperties": true }, "featureFlags": { "type": "object", "additionalProperties": true }, "theme": { "type": "object", "additionalProperties": true }, "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "allowedRedirectUrls": { "type": "array", "items": { "type": "string" } }, "oidcProviders": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authAbuseConfig": { "type": "object", "additionalProperties": true }, "appClients": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "testAccount": { "type": "object", "additionalProperties": true }, "gasSponsorshipConfig": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/tenants/{id}/config": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Tenant Config" ], "summary": "Get tenant control-plane config", "description": "Tenant control-plane configuration. Reads require tenant-level auth except /tenants/config, which is public default discovery for unauthenticated SDK bootstraps.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "tenantId" ], "properties": { "tenantId": { "type": "string" }, "displayName": { "type": "string" }, "policyExposure": { "type": "object", "additionalProperties": true }, "policyTemplates": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "secretRoutePresets": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "approvalConfig": { "type": "object", "additionalProperties": true }, "featureFlags": { "type": "object", "additionalProperties": true }, "theme": { "type": "object", "additionalProperties": true }, "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "allowedRedirectUrls": { "type": "array", "items": { "type": "string" } }, "oidcProviders": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authAbuseConfig": { "type": "object", "additionalProperties": true }, "appClients": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "testAccount": { "type": "object", "additionalProperties": true }, "gasSponsorshipConfig": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "put": { "tags": [ "Tenant Config" ], "summary": "Update tenant control-plane config", "description": "Requires owner/admin session with recent MFA. Updates policy exposure, policy templates, feature flags, app clients, allowed origins, redirect URLs, MFA/auth-abuse config, gas sponsorship config, and presentation settings.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tenantId" ], "properties": { "tenantId": { "type": "string" }, "displayName": { "type": "string" }, "policyExposure": { "type": "object", "additionalProperties": true }, "policyTemplates": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "secretRoutePresets": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "approvalConfig": { "type": "object", "additionalProperties": true }, "featureFlags": { "type": "object", "additionalProperties": true }, "theme": { "type": "object", "additionalProperties": true }, "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "allowedRedirectUrls": { "type": "array", "items": { "type": "string" } }, "oidcProviders": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authAbuseConfig": { "type": "object", "additionalProperties": true }, "appClients": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "testAccount": { "type": "object", "additionalProperties": true }, "gasSponsorshipConfig": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "tenantId" ], "properties": { "tenantId": { "type": "string" }, "displayName": { "type": "string" }, "policyExposure": { "type": "object", "additionalProperties": true }, "policyTemplates": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "secretRoutePresets": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "approvalConfig": { "type": "object", "additionalProperties": true }, "featureFlags": { "type": "object", "additionalProperties": true }, "theme": { "type": "object", "additionalProperties": true }, "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "allowedRedirectUrls": { "type": "array", "items": { "type": "string" } }, "oidcProviders": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authAbuseConfig": { "type": "object", "additionalProperties": true }, "appClients": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "testAccount": { "type": "object", "additionalProperties": true }, "gasSponsorshipConfig": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/tenants", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/tenants/{id}/config/templates": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Tenant Config" ], "summary": "List tenant policy templates", "description": "Returns tenant policy templates. Non-admin tenant auth receives policy-exposure-redacted templates.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/tenants/{id}/config/templates/{name}/apply": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Tenant Config" ], "summary": "Apply a tenant policy template to an agent", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot mutate tenant security configuration. Applies a validated policy template to an agent, with optional per-field overrides restricted to template customizable fields.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId" ], "properties": { "agentId": { "type": "string" }, "overrides": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "templateId", "templateName", "agentId", "policiesApplied", "policies" ], "properties": { "templateId": { "type": "string" }, "templateName": { "type": "string" }, "agentId": { "type": "string" }, "policiesApplied": { "type": "integer", "minimum": 0 }, "policies": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/tenants", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/tenants/{id}/auth-abuse-config": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Tenant Config" ], "summary": "Get tenant auth-abuse config", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot mutate tenant security configuration.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "authAbuseConfig" ], "properties": { "authAbuseConfig": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "put": { "tags": [ "Tenant Config" ], "summary": "Update tenant auth-abuse config", "description": "Requires owner/admin session with recent MFA. Updates CAPTCHA, allowlist/denylist, MFA, and wallet/phone/email abuse controls after server-side normalization.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "authAbuseConfig" ], "properties": { "authAbuseConfig": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "authAbuseConfig" ], "properties": { "authAbuseConfig": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/tenants", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/tenants/{id}/security-checklist": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Tenant Config" ], "summary": "Get tenant security checklist", "description": "Requires owner/admin session with recent MFA. Summarizes tenant origin, redirect, app-client, app-secret, and request-signing-key hardening status.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "tenantId", "generatedAt", "summary", "items" ], "properties": { "tenantId": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "summary": { "type": "object", "required": [ "pass", "warning", "fail" ], "properties": { "pass": { "type": "integer", "minimum": 0 }, "warning": { "type": "integer", "minimum": 0 }, "fail": { "type": "integer", "minimum": 0 } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "status", "description" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pass", "warning", "fail" ] }, "description": { "type": "string" }, "remediation": { "type": "string" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/tenants/{id}/idempotency-metrics": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Tenant Config" ], "summary": "Get tenant idempotency metrics", "description": "Requires owner/admin session with recent MFA. Returns privacy-preserving idempotency counters for sensitive request replay diagnostics.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true, "description": "Privacy-preserving idempotency counters for the tenant. Shape can evolve with middleware storage backends." } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/tenants/{id}/idempotency-metrics/export": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Tenant Config" ], "summary": "Export tenant idempotency metrics", "description": "Requires owner/admin session with recent MFA. Exports one privacy-preserving CSV snapshot of idempotency counters for sensitive request replay diagnostics. The export never includes idempotency keys, request bodies, stored response bodies, or credential material.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "CSV idempotency metrics snapshot", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/tenants/{id}/request-signing-keys": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Tenant Config" ], "summary": "List tenant request-signing keys", "description": "Requires owner/admin session with recent MFA. Returns metadata only; signing secrets are never returned by list responses.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "name", "secretPrefix", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "secretPrefix": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "retiring", "revoked" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Tenant Config" ], "summary": "Create or rotate a tenant request-signing key", "description": "Requires owner/admin session with recent MFA. Creates a new active request-signing key, retires currently active keys, and returns the signingSecret exactly once.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "key", "signingSecret" ], "properties": { "key": { "type": "object", "required": [ "id", "tenantId", "name", "secretPrefix", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "secretPrefix": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "retiring", "revoked" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "signingSecret": { "type": "string", "description": "One-time tenant request signing secret. It is returned only from key creation responses." } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/tenants", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/tenants/{id}/request-signing-keys/{keyId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Tenant Config" ], "summary": "Revoke a tenant request-signing key", "description": "Requires an owner/admin browser session with recent MFA. Tenant API keys and agent tokens cannot mutate tenant security configuration.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "object", "required": [ "id", "tenantId", "name", "secretPrefix", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "secretPrefix": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "retiring", "revoked" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/tenants", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/platform/tenants/{tenantId}/members": { "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Platform Tenants" ], "summary": "List tenant members", "description": "Requires a platform key with platform:tenant-member:read. Returns tenant-scoped membership rows without global user secrets.", "security": [ { "platformKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "userId", "role", "email" ], "properties": { "userId": { "type": "string" }, "tenantId": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "joinedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Platform Tenants" ], "summary": "Add a tenant member by email", "description": "Requires a platform key with platform:tenant-member:write. Creates the user if needed, audits the membership add before mutating identity state, and preserves existing memberships idempotently.", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "userId", "role", "email" ], "properties": { "userId": { "type": "string" }, "tenantId": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "joinedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/platform", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/platform/tenants/{tenantId}/members/{userId}": { "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "tags": [ "Platform Tenants" ], "summary": "Update a tenant member role", "description": "Requires platform:tenant-member:write. Role changes revoke the member's tenant refresh tokens, audit the previous role, and fail closed when they would downgrade the sole active owner.", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "userId", "tenantId", "role" ], "properties": { "userId": { "type": "string" }, "tenantId": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/platform", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } }, "delete": { "tags": [ "Platform Tenants" ], "summary": "Remove a tenant member", "description": "Requires platform:tenant-member:write. Removal revokes user tokens and refuses to remove the sole active tenant owner.", "security": [ { "platformKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object" } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/platform", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/platform/tenants/{tenantId}/invitations": { "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Platform Tenants" ], "summary": "List tenant invitations", "description": "Requires platform:tenant-member:read. Invitation tokens and token hashes are never returned by list responses.", "security": [ { "platformKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "accepted", "revoked", "expired", "all" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "invitations" ], "properties": { "invitations": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "email", "role", "status", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "revoked", "expired" ] }, "invitedByUserId": { "type": [ "string", "null" ] }, "acceptedByUserId": { "type": [ "string", "null" ] }, "acceptedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Platform Tenants" ], "summary": "Create a tenant invitation", "description": "Requires platform:tenant-member:write. Returns the single-use invitation token exactly once, stores only its hash, sets no-store response headers at runtime, and audits create/rollback behavior around pending invitation replacement.", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "expiresInSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "invitedByUserId": { "type": "string" }, "sendEmail": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "invitation", "token", "emailSent" ], "properties": { "invitation": { "type": "object", "required": [ "id", "tenantId", "email", "role", "status", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "revoked", "expired" ] }, "invitedByUserId": { "type": [ "string", "null" ] }, "acceptedByUserId": { "type": [ "string", "null" ] }, "acceptedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "token": { "type": "string" }, "emailSent": { "type": "boolean" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/platform", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/platform/tenants/{tenantId}/invitations/{invitationId}": { "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Platform Tenants" ], "summary": "Revoke a pending tenant invitation", "description": "Requires platform:tenant-member:write. Revokes only pending invitations in the addressed tenant and rolls the status back if the final audit event fails.", "security": [ { "platformKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object" } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/platform", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/platform/users": { "post": { "tags": [ "Platform Users" ], "summary": "Create or pre-provision a user", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "emailVerified": { "type": "boolean" }, "name": { "type": "string" }, "customMetadata": { "type": "object", "additionalProperties": true }, "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "externalId": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string" }, "isNew": { "type": "boolean" }, "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" } } } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string" }, "isNew": { "type": "boolean" }, "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/platform", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/platform/users/lookup": { "get": { "tags": [ "Platform Users" ], "summary": "Look up a platform user identity", "security": [ { "platformKey": [] } ], "parameters": [ { "name": "email", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "walletAddress", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "walletExternalId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "smartWalletId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "customAuthId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "providerAccountId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "tenantId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "user": { "anyOf": [ { "type": "object", "additionalProperties": true, "properties": { "userId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "emailVerified": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "walletAddress": { "type": [ "string", "null" ] }, "walletChain": { "type": [ "string", "null" ] }, "customMetadata": { "type": "object", "additionalProperties": true }, "deactivatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantIds": { "type": "array", "items": { "type": "string" } }, "linkedAccounts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "walletExternalIds": { "type": "array", "items": { "type": "object", "properties": { "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "externalId": { "type": "string" } } } } } }, { "type": "null" } ] } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } }, "post": { "tags": [ "Platform Users" ], "summary": "Look up a platform user identity", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "user": { "anyOf": [ { "type": "object", "additionalProperties": true, "properties": { "userId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "emailVerified": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "walletAddress": { "type": [ "string", "null" ] }, "walletChain": { "type": [ "string", "null" ] }, "customMetadata": { "type": "object", "additionalProperties": true }, "deactivatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantIds": { "type": "array", "items": { "type": "string" } }, "linkedAccounts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "walletExternalIds": { "type": "array", "items": { "type": "object", "properties": { "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "externalId": { "type": "string" } } } } } }, { "type": "null" } ] } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/platform", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/platform/users/{userId}/wallet/external-id": { "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Platform Users" ], "summary": "Assign an immutable wallet external ID to a user", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tenantId" ], "properties": { "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "externalId": { "type": "string" } }, "anyOf": [ { "required": [ "walletExternalId" ] }, { "required": [ "externalId" ] } ] } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string" }, "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "field": { "type": "string", "const": "walletExternalId" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/platform", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/platform/users/wallet/external-id": { "post": { "tags": [ "Platform Users" ], "summary": "Resolve a wallet external ID", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tenantId" ], "properties": { "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "externalId": { "type": "string" } }, "anyOf": [ { "required": [ "walletExternalId" ] }, { "required": [ "externalId" ] } ] } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "user": { "anyOf": [ { "type": "object", "additionalProperties": true, "properties": { "userId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "emailVerified": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "walletAddress": { "type": [ "string", "null" ] }, "walletChain": { "type": [ "string", "null" ] }, "customMetadata": { "type": "object", "additionalProperties": true }, "deactivatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantIds": { "type": "array", "items": { "type": "string" } }, "linkedAccounts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "walletExternalIds": { "type": "array", "items": { "type": "object", "properties": { "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "externalId": { "type": "string" } } } } } }, { "type": "null" } ] } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/platform", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/platform/users/wallet/external-id/connect-or-create": { "post": { "tags": [ "Platform Users" ], "summary": "Connect or create a user by wallet external ID", "security": [ { "platformKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tenantId" ], "properties": { "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "externalId": { "type": "string" }, "email": { "type": "string", "format": "email" }, "emailVerified": { "type": "boolean" }, "name": { "type": "string" }, "customMetadata": { "type": "object", "additionalProperties": true }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "anyOf": [ { "required": [ "walletExternalId" ] }, { "required": [ "externalId" ] } ] } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string" }, "isNew": { "type": "boolean" }, "createdExternalId": { "type": "boolean" }, "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "user": { "type": "object", "additionalProperties": true, "properties": { "userId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "emailVerified": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "walletAddress": { "type": [ "string", "null" ] }, "walletChain": { "type": [ "string", "null" ] }, "customMetadata": { "type": "object", "additionalProperties": true }, "deactivatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantIds": { "type": "array", "items": { "type": "string" } }, "linkedAccounts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "walletExternalIds": { "type": "array", "items": { "type": "object", "properties": { "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "externalId": { "type": "string" } } } } } } } } } } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string" }, "isNew": { "type": "boolean" }, "createdExternalId": { "type": "boolean" }, "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "user": { "type": "object", "additionalProperties": true, "properties": { "userId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "emailVerified": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "walletAddress": { "type": [ "string", "null" ] }, "walletChain": { "type": [ "string", "null" ] }, "customMetadata": { "type": "object", "additionalProperties": true }, "deactivatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantIds": { "type": "array", "items": { "type": "string" } }, "linkedAccounts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "walletExternalIds": { "type": "array", "items": { "type": "object", "properties": { "tenantId": { "type": "string" }, "walletExternalId": { "type": "string" }, "externalId": { "type": "string" } } } } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/platform", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/platform/tenants/{tenantId}/users": { "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Platform Users" ], "summary": "Search tenant users, optionally by wallet external ID", "security": [ { "platformKey": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "walletExternalId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/user/me/tenants/{tenantId}/users/wallet-policy/violations": { "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Tenant Users" ], "summary": "Report one third-party wallet policy violations", "description": "Requires an authenticated tenant admin user with recent MFA. Returns a read-only report of existing users that have multiple linked EVM/Solana third-party wallets so operators can review global linked-account remediation safely.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "tenantId", "policyEnabled", "violations", "total", "limit", "offset" ], "properties": { "tenantId": { "type": "string" }, "policyEnabled": { "type": "boolean" }, "violations": { "type": "array", "items": { "type": "object", "required": [ "userId", "email", "name", "role", "walletCount", "wallets" ], "properties": { "userId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "walletCount": { "type": "integer", "minimum": 2 }, "wallets": { "type": "array", "minItems": 2, "items": { "type": "object", "required": [ "accountId", "provider", "providerAccountId" ], "properties": { "accountId": { "type": "string" }, "provider": { "type": "string", "enum": [ "wallet:ethereum", "wallet:solana" ] }, "providerAccountId": { "type": "string" } } } } } } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1 }, "offset": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/user/me/tenants/{tenantId}/users/{userId}/wallet-policy/wallets/{accountId}": { "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Tenant Users" ], "summary": "Remediate one third-party wallet policy violation", "description": "Requires an authenticated tenant owner/admin user with recent MFA and a session scoped to the tenant. Deletes one selected EVM/Solana linked wallet from a tenant member, refuses to remove the user's last login method, revokes the remediated user's refresh tokens, writes authorized/final audit events, and dispatches a redacted user.unlinked_account webhook.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "deleted", "accountId", "provider", "providerAccountId", "issuedBefore" ], "properties": { "deleted": { "type": "boolean", "const": true }, "accountId": { "type": "string" }, "provider": { "type": "string", "enum": [ "wallet:ethereum", "wallet:solana" ] }, "providerAccountId": { "type": "string" }, "issuedBefore": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/user", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/platform/apps/gas_spend": { "get": { "tags": [ "Platform Apps" ], "summary": "Get sponsored gas spend, including wallet external ID filters", "security": [ { "platformKey": [] } ], "parameters": [ { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "wallet_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "wallet_external_ids", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "walletExternalIds", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_timestamp", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "end_timestamp", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/vault/{agentId}/import/init": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Vault" ], "summary": "Initialize an encrypted private-key import session", "description": "Requires an authenticated tenant owner/admin user with recent MFA plus the audited import feature flags. Returns a short-lived X25519 public key and AAD fields for a one-time encrypted import session. Responses are no-store and do not contain private-key material.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "chain" ], "properties": { "chain": { "type": "string", "enum": [ "evm", "solana" ] } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "importSessionId", "publicKey", "algorithm", "expiresAt", "aad" ], "properties": { "importSessionId": { "type": "string" }, "publicKey": { "type": "string", "description": "Base64url DER-encoded X25519 SPKI public key for this one-time import session." }, "algorithm": { "type": "string", "const": "X25519-HKDF-SHA256-AES-256-GCM" }, "expiresAt": { "type": "string", "format": "date-time" }, "aad": { "type": "object", "required": [ "importSessionId", "tenantId", "agentId", "chain" ], "properties": { "importSessionId": { "type": "string" }, "tenantId": { "type": "string" }, "agentId": { "type": "string" }, "chain": { "type": "string", "enum": [ "evm", "solana" ] } } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/vault", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/vault/{agentId}/import/submit": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Vault" ], "summary": "Submit an encrypted private-key import envelope", "description": "Consumes a one-time encrypted import session and imports the decrypted EVM or Solana private key into encrypted vault storage. Plaintext `privateKey` fields are rejected; audit metadata records only chain/session/address metadata.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "importSessionId", "ephemeralPublicKey", "iv", "ciphertext", "tag" ], "properties": { "importSessionId": { "type": "string" }, "ephemeralPublicKey": { "type": "string", "description": "Base64url DER-encoded X25519 SPKI public key generated by the client." }, "iv": { "type": "string", "description": "Base64url AES-GCM nonce, 12 bytes before encoding." }, "ciphertext": { "type": "string", "description": "Base64url encrypted private key bytes. Plaintext privateKey is rejected." }, "tag": { "type": "string", "description": "Base64url AES-GCM authentication tag." } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "agentId", "walletAddress", "chain" ], "properties": { "agentId": { "type": "string" }, "walletAddress": { "type": "string" }, "chain": { "type": "string", "enum": [ "evm", "solana" ] } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/vault", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/vault/{agentId}/sign": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Vault" ], "summary": "Sign or broadcast a governed transaction", "description": "Evaluates current agent policy and signs a transaction. Broadcast requests require an Idempotency-Key. HTTP 202 may mean either pending_approval or outcome_unknown; outcome_unknown includes the deterministic transaction hash and requires receipt reconciliation before any retry.", "security": [ { "tenantApiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "to", "value" ], "properties": { "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 }, "nonce": { "type": "integer", "minimum": 0 }, "gasLimit": { "type": "string" }, "broadcast": { "type": "boolean", "default": true }, "venue": { "type": "string" }, "walletAddress": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "txId" ], "properties": { "txId": { "type": "string" }, "txHash": { "type": "string" }, "signedTx": { "type": "string" } }, "oneOf": [ { "required": [ "txHash" ] }, { "required": [ "signedTx" ] } ] } } } } } }, "202": { "description": "JSON response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "ok", "error", "data" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" }, "data": { "type": "object", "required": [ "txId", "status", "results" ], "properties": { "txId": { "type": "string" }, "status": { "type": "string", "const": "pending_approval" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, { "type": "object", "additionalProperties": false, "required": [ "ok", "error", "data" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" }, "data": { "type": "object", "additionalProperties": false, "required": [ "code", "txId", "txHash", "reconciliationRequired" ], "properties": { "code": { "type": "string", "const": "external_broadcast_outcome_unknown" }, "txId": { "type": "string" }, "txHash": { "type": "string" }, "reconciliationRequired": { "type": "boolean", "const": true } } } } } ] } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "428": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "500": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/vault", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/vault/{agentId}/actions/transfer/quote": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Vault" ], "summary": "Quote an EVM transfer wallet action", "description": "Requires an owner/admin browser session with recent MFA. Native transfers and ERC20 transfer-shaped requests share the same quote schema; ERC20 execution requires a constrained contract-allowlist selector policy before signing.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string" }, "value": { "type": "string" }, "amountWei": { "type": "string" }, "token": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 }, "broadcast": { "type": "boolean" }, "referenceId": { "type": "string" }, "sponsor": { "type": "boolean" } }, "anyOf": [ { "required": [ "value" ] }, { "required": [ "amountWei" ] } ] } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "quoteId", "type", "chainId", "from", "to", "value", "token", "expiresAt", "request" ], "properties": { "quoteId": { "type": "string" }, "type": { "type": "string", "const": "transfer" }, "chainId": { "type": "integer", "minimum": 1 }, "from": { "type": "string" }, "to": { "type": "string" }, "value": { "type": "string" }, "token": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "request": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string" }, "value": { "type": "string" }, "amountWei": { "type": "string" }, "token": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 }, "broadcast": { "type": "boolean" }, "referenceId": { "type": "string" }, "sponsor": { "type": "boolean" } }, "anyOf": [ { "required": [ "value" ] }, { "required": [ "amountWei" ] } ] } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "500": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "501": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "503": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/vault", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/vault/{agentId}/actions/transfer": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Vault" ], "summary": "Create an EVM transfer wallet action", "description": "Creates and signs/broadcasts a native EVM transfer or selector-gated ERC20 transfer when policy allows. ERC20 transfers sign the token contract with `transfer(address,uint256)` calldata, zero native value, token/recipient/amount action metadata, and a required constrained `contract-allowlist` selector policy. Policy-denied actions return 403 with status `rejected`; manual-approval actions return 202 with status `pending_approval`; RPC failures return 500/502 with the created action ID when available. Broadcast actions require idempotency.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string" }, "value": { "type": "string" }, "amountWei": { "type": "string" }, "token": { "type": "string" }, "chainId": { "type": "integer", "minimum": 1 }, "broadcast": { "type": "boolean" }, "referenceId": { "type": "string" }, "sponsor": { "type": "boolean" } }, "anyOf": [ { "required": [ "value" ] }, { "required": [ "amountWei" ] } ] } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "type", "status", "chainId", "to", "value", "token" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "transfer" }, "status": { "type": "string", "enum": [ "pending_approval", "rejected", "signed", "broadcast", "confirmed", "failed", "outcome_unknown", "retired" ] }, "chainId": { "type": "integer", "minimum": 1 }, "to": { "type": "string" }, "value": { "type": "string" }, "token": { "type": "string" }, "txHash": { "type": "string" }, "signedTx": { "type": "string" }, "sponsorship": { "type": "object", "properties": { "requested": { "type": "boolean" }, "sponsored": { "type": "boolean" }, "provider": { "type": "string" }, "mode": { "type": "string" }, "estimatedUsd": { "type": [ "number", "null" ] } } }, "policyResults": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "createdAt": { "type": "string", "format": "date-time" }, "signedAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "format": "date-time" } } } } } } } }, "202": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "type", "status", "chainId", "to", "value", "token" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "transfer" }, "status": { "type": "string", "enum": [ "pending_approval", "rejected", "signed", "broadcast", "confirmed", "failed", "outcome_unknown", "retired" ] }, "chainId": { "type": "integer", "minimum": 1 }, "to": { "type": "string" }, "value": { "type": "string" }, "token": { "type": "string" }, "txHash": { "type": "string" }, "signedTx": { "type": "string" }, "sponsorship": { "type": "object", "properties": { "requested": { "type": "boolean" }, "sponsored": { "type": "boolean" }, "provider": { "type": "string" }, "mode": { "type": "string" }, "estimatedUsd": { "type": [ "number", "null" ] } } }, "policyResults": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "createdAt": { "type": "string", "format": "date-time" }, "signedAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "500": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "501": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "503": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/vault", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/vault/{agentId}/actions/send-calls": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Vault" ], "summary": "Create an EVM batch-call wallet action intent", "description": "Creates a batch-call action that currently resolves to `pending_approval` or `rejected`; approved send-calls execution remains an approval/intents workflow. Calldata-bearing calls are rejected unless unsafe contract-call signing is explicitly enabled.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "calls" ], "properties": { "calls": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" } } } }, "chainId": { "type": "integer", "minimum": 1 }, "broadcast": { "type": "boolean" }, "referenceId": { "type": "string" }, "sponsor": { "type": "boolean" } } } } } }, "responses": { "202": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "type", "status", "chainId", "calls", "totalValue" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "send_calls" }, "status": { "type": "string", "enum": [ "pending_approval", "rejected" ] }, "chainId": { "type": "integer", "minimum": 1 }, "calls": { "type": "array", "items": { "type": "object", "required": [ "to", "value" ], "properties": { "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" } } } }, "totalValue": { "type": "string" }, "sponsorship": { "type": "object", "properties": { "requested": { "type": "boolean" }, "sponsored": { "type": "boolean" }, "provider": { "type": "string" }, "mode": { "type": "string" }, "estimatedUsd": { "type": [ "number", "null" ] } } }, "policyResults": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "500": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "501": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "503": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/vault", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/vault/{agentId}/actions/{actionId}": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Vault" ], "summary": "Get transfer wallet action status", "description": "Returns status for transfer wallet actions. Send-calls status is currently exposed through transaction/intents history, not this transfer-only status endpoint.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "type", "status", "chainId", "to", "value", "token" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "transfer" }, "status": { "type": "string", "enum": [ "pending_approval", "rejected", "signed", "broadcast", "confirmed", "failed", "outcome_unknown", "retired" ] }, "chainId": { "type": "integer", "minimum": 1 }, "to": { "type": "string" }, "value": { "type": "string" }, "token": { "type": "string" }, "txHash": { "type": "string" }, "signedTx": { "type": "string" }, "sponsorship": { "type": "object", "properties": { "requested": { "type": "boolean" }, "sponsored": { "type": "boolean" }, "provider": { "type": "string" }, "mode": { "type": "string" }, "estimatedUsd": { "type": [ "number", "null" ] } } }, "policyResults": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "createdAt": { "type": "string", "format": "date-time" }, "signedAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/vault/{agentId}/sign-bitcoin-psbt": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Vault" ], "summary": "Sign a Bitcoin PSBT with a scoped agent wallet", "description": "Requires agent access plus owner/admin recent MFA or delegated signer credentials with `sign_transaction`. The route decodes standard Bitcoin PSBT destination outputs, computes input/output/fee totals before signing, rejects excessive fees, evaluates both destination outputs and aggregate destination+fee spend against the agent policy set, and records the signed spend for future policy counters. It also requires an enabled `raw-signing-chain` policy that explicitly allows `bitcoin` and `secp256k1`.", "security": [ { "bearerAuth": [] }, { "tenantApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletScope", "psbtBase64" ], "properties": { "walletScope": { "type": "string" }, "psbtBase64": { "type": "string", "description": "Base64-encoded PSBT" }, "finalize": { "type": "boolean", "description": "When true, finalize the signed PSBT and return raw transaction hex plus txid/fee metadata. No broadcast is performed." }, "referenceId": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "signedPsbtBase64", "signedInputs", "addressType", "network", "walletScope", "walletAddress", "transactionId" ], "properties": { "signedPsbtBase64": { "type": "string" }, "signedInputs": { "type": "integer", "minimum": 1 }, "addressType": { "type": "string", "enum": [ "p2wpkh", "p2tr" ] }, "network": { "type": "string", "enum": [ "mainnet", "testnet" ] }, "walletScope": { "type": "string" }, "walletAddress": { "type": "string" }, "transactionId": { "type": "string" }, "finalizedTxHex": { "type": "string" }, "txId": { "type": "string" }, "vsize": { "type": "integer", "minimum": 1 }, "feeSats": { "type": "string" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/vault", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/vault/{agentId}/monero/balance": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Vault" ], "summary": "Get a scoped Monero wallet balance", "description": "Reads the wallet balance through the self-hosted monero-wallet-rpc sidecar (explicitly configured daemon; keys never leave the host). Returns 503 when Monero support is not configured. The first call after idle time refreshes the wallet scan and may take a few seconds.", "security": [ { "bearerAuth": [] }, { "tenantApiKey": [] } ], "parameters": [ { "name": "walletScope", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "balancePiconero", "unlockedPiconero", "blocksToUnlock", "syncedHeight", "walletScope", "walletAddress", "network" ], "properties": { "balancePiconero": { "type": "string", "description": "Total balance in piconero" }, "unlockedPiconero": { "type": "string", "description": "Spendable (unlocked) balance in piconero" }, "blocksToUnlock": { "type": "integer", "minimum": 0 }, "syncedHeight": { "type": "integer", "minimum": 0 }, "walletScope": { "type": "string" }, "walletAddress": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "stagenet" ] } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/vault/{agentId}/monero/transfer": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Vault" ], "summary": "Build, sign, and relay a Monero transfer", "description": "Requires agent access plus owner/admin recent MFA or delegated signer credentials with `sign_transaction`, an enabled `raw-signing-chain` policy that explicitly allows `monero` and `ed25519`, and an Idempotency-Key header. Destinations are policy-evaluated first; the vault's wallet2 backend then builds the transaction without relaying so the exact fee is known, the fee-inclusive aggregate spend is re-evaluated, and only then is the transaction relayed. The vault never accepts a caller-built transaction blob. USD-denominated policy rules fail closed for Monero (no XMR price source) — use piconero-denominated limits.", "security": [ { "bearerAuth": [] }, { "tenantApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletScope", "destinations" ], "properties": { "walletScope": { "type": "string", "description": "Monero wallet scope, e.g. monero:mainnet:0" }, "destinations": { "type": "array", "minItems": 1, "maxItems": 15, "items": { "type": "object", "required": [ "address", "amountPiconero" ], "properties": { "address": { "type": "string", "description": "Standard, subaddress, or integrated Monero address" }, "amountPiconero": { "type": "string", "description": "Positive decimal amount in piconero (1 XMR = 10^12)" } } } }, "priority": { "type": "integer", "minimum": 0, "maximum": 3, "description": "wallet2 fee priority: 0 default … 3 elevated" }, "referenceId": { "type": "string" } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "transactionId", "txHash", "feePiconero", "amountPiconero", "totalPiconero", "walletScope", "walletAddress", "network" ], "properties": { "transactionId": { "type": "string" }, "txHash": { "type": "string", "description": "64-hex Monero transaction hash" }, "feePiconero": { "type": "string" }, "amountPiconero": { "type": "string" }, "totalPiconero": { "type": "string" }, "walletScope": { "type": "string" }, "walletAddress": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "stagenet" ] } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/vault", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } }, "/vault/{agentId}/transactions": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Vault" ], "summary": "List transactions with optional reference ID filtering", "security": [ { "bearerAuth": [] }, { "tenantApiKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "actionType", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "txHash", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "referenceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "reference_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } } } }, "/vault/{agentId}/transactions/{txId}/retire-signed": { "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "txId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Vault" ], "summary": "Authoritatively retire a signed transaction artifact", "description": "Requires an owner/admin browser session with recent MFA. Solana retirement succeeds only when the exact deterministic signature is absent from chain history and its byte-classified ordinary blockhash is expired. Durable-nonce and unclassified artifacts remain blocked. Landed artifacts are reconciled instead. Provider uncertainty and unsupported EVM artifacts remain non-terminal.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "txId", "status", "artifactId", "retiredAt" ], "properties": { "txId": { "type": "string" }, "status": { "type": "string", "const": "retired" }, "artifactId": { "type": "string" }, "retiredAt": { "type": "string" } } } } } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "408": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } }, "502": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "X-Steward-Request-Timestamp", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO timestamp. Sensitive mutating routes require this or X-Steward-Request-Expires-At when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Request-Expires-At", "in": "header", "required": false, "description": "Unix seconds, Unix milliseconds, or HTTP/ISO expiry time. Sensitive mutating routes require this or X-Steward-Request-Timestamp when request-expiry or request signatures are enforced.", "schema": { "type": "string" } }, { "name": "X-Steward-Signature", "in": "header", "required": false, "description": "Authorization signature for sensitive mutating routes when STEWARD_REQUIRE_AUTH_SIGNATURE=true or production enforcement is enabled. Use v1= or p256=.", "schema": { "type": "string" } }, { "name": "X-Steward-Signing-Key-Id", "in": "header", "required": false, "description": "Tenant request-signing key id used to select a managed HMAC signing key. Required when signing with a managed tenant key; omit only for static or app-client signing secrets.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required for signed sensitive requests and recommended for all sensitive mutating requests. Replays are scoped to authenticated or explicitly signed contexts.", "schema": { "type": "string" } } ], "x-steward-hardening": { "sensitive": true, "sensitivePrefix": "/vault", "requestExpiry": { "requiredWhen": "STEWARD_REQUIRE_REQUEST_EXPIRY=true", "acceptedHeaders": [ "X-Steward-Request-Timestamp", "X-Steward-Request-Expires-At" ] }, "authorizationSignature": { "requiredWhen": "STEWARD_REQUIRE_AUTH_SIGNATURE=true", "header": "X-Steward-Signature", "schemes": [ "v1=hmac-sha256", "p256=ecdsa-secp256r1" ], "managedTenantKeyHeader": "X-Steward-Signing-Key-Id", "requiredForManagedTenantKey": true }, "idempotency": { "header": "Idempotency-Key", "requiredForSignedRequests": true, "replayStorage": "enabled when callers provide a key in a replay-safe authenticated context" } } } } } }