{ "openapi": "3.0.3", "info": { "title": "Coinbax Core API", "version": "1.0.0", "description": "Admin backend API for the Coinbax blockchain payment platform.\n\n## Authentication\n\nMost endpoints require JWT authentication. Include the access token in the Authorization header:\n\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n\n## API Versioning\n\nAll API endpoints are versioned. The current version is `v1`:\n\n```\nhttps://core.coinbax.com/api/v1/workspaces\n```\n\n## Rate Limiting\n\nAPI requests are rate limited based on authentication tier:\n- **Public endpoints:** 20 requests per minute\n- **Standard (authenticated):** 100 requests per minute\n- **High-frequency:** 1000 requests per minute\n- **Admin operations:** 50 requests per minute\n\nRate limit headers are included in all responses:\n```\nX-RateLimit-Limit: 100\nX-RateLimit-Remaining: 87\nX-RateLimit-Reset: 1735073400\n```\n\n## Pagination\n\nList endpoints support pagination via `page` and `limit` query parameters:\n- Default limit: 20\n- Maximum limit: 100\n\n## Response Format\n\nAll responses follow a standard envelope:\n\n**Success:**\n```json\n{\n \"success\": true,\n \"data\": { ... },\n \"meta\": {\n \"timestamp\": \"2026-02-24T12:00:00Z\",\n \"requestId\": \"req_abc123\",\n \"pagination\": { \"page\": 1, \"limit\": 20, \"total\": 150, \"totalPages\": 8 }\n }\n}\n```\n\n**Error:**\n```json\n{\n \"success\": false,\n \"data\": null,\n \"error\": {\n \"code\": \"ERROR_CODE\",\n \"message\": \"Human readable message\",\n \"statusCode\": 400,\n \"details\": { ... }\n },\n \"meta\": {\n \"timestamp\": \"2026-02-24T12:00:00Z\",\n \"requestId\": \"req_abc123\"\n }\n}\n```\n", "contact": { "name": "Coinbax Support", "email": "support@coinbax.com", "url": "https://docs.coinbax.com" }, "license": { "name": "Proprietary", "url": "https://coinbax.com/terms" } }, "servers": [ { "url": "https://core.coinbax.com/api/v1", "description": "Production server" }, { "url": "https://core-staging.coinbax.com/api/v1", "description": "Staging server" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "User authentication and session management" }, { "name": "Workspaces", "description": "Workspace (tenant) management" }, { "name": "Workspace Customers", "description": "Customer management within workspaces" }, { "name": "Workspace Transactions", "description": "Transaction management within workspaces" }, { "name": "Workspace Webhooks", "description": "Webhook management for workspaces" }, { "name": "Workspace OAuth", "description": "OAuth client management for workspaces" }, { "name": "Customers", "description": "Global customer management (admin only)" }, { "name": "Transactions", "description": "Global transaction management" }, { "name": "Users", "description": "Admin user management" }, { "name": "Wallet Configs", "description": "Wallet provider configuration" }, { "name": "Notifications", "description": "User notifications" }, { "name": "Settings", "description": "Application settings" }, { "name": "Audit Logs", "description": "Audit log access" }, { "name": "Smart Contracts", "description": "Smart contract management" }, { "name": "Integrations", "description": "Third-party integrations" }, { "name": "Health", "description": "System health checks" }, { "name": "Onboarding", "description": "User onboarding flow" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT access token obtained from `/auth/login` endpoint.\n\nInclude in Authorization header: `Authorization: Bearer YOUR_TOKEN`\n\nTokens expire in 1 hour. Use `/auth/refresh` to obtain new tokens.\n" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Workspace API key for external integrations.\n\nInclude in header: `X-API-Key: YOUR_WORKSPACE_API_KEY`\n" }, "internalApiKey": { "type": "apiKey", "in": "header", "name": "X-Internal-API-Key", "description": "Internal API key for service-to-service communication.\nThis is not intended for external use.\n" } }, "schemas": { "SuccessResponse": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true for successful responses", "example": true }, "data": { "description": "Response data (structure varies by endpoint)" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ErrorResponse": { "type": "object", "required": [ "success", "error", "meta" ], "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always false for error responses", "example": false }, "data": { "type": "object", "nullable": true, "description": "Always null for error responses", "example": null }, "error": { "$ref": "#/components/schemas/Error" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Error": { "type": "object", "required": [ "code", "message", "statusCode" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Validation failed" }, "statusCode": { "type": "integer", "description": "HTTP status code", "example": 400 }, "details": { "type": "object", "additionalProperties": true, "description": "Additional error details (optional)", "example": { "field": "email", "reason": "Invalid email format" } } } }, "Meta": { "type": "object", "required": [ "timestamp", "requestId" ], "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Response timestamp", "example": "2026-02-24T12:00:00.000Z" }, "requestId": { "type": "string", "description": "Unique request identifier for debugging", "example": "550e8400-e29b-41d4-a716-446655440000" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Pagination": { "type": "object", "required": [ "page", "limit", "total", "totalPages" ], "properties": { "page": { "type": "integer", "minimum": 1, "description": "Current page number (1-indexed)", "example": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Items per page", "example": 20 }, "total": { "type": "integer", "minimum": 0, "description": "Total number of items", "example": 150 }, "totalPages": { "type": "integer", "minimum": 0, "description": "Total number of pages", "example": 8 } } }, "User": { "type": "object", "required": [ "id", "email", "role" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "User unique identifier", "example": "550e8400-e29b-41d4-a716-446655440000" }, "email": { "type": "string", "format": "email", "description": "User's email address", "example": "admin@coinbax.com" }, "firstName": { "type": "string", "description": "User's first name", "example": "Admin" }, "lastName": { "type": "string", "description": "User's last name", "example": "User" }, "role": { "type": "string", "enum": [ "SUPER_ADMIN", "ADMIN", "CLIENT" ], "description": "User's role", "example": "ADMIN" }, "workspaceId": { "type": "string", "format": "uuid", "nullable": true, "description": "Associated workspace ID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "emailVerified": { "type": "boolean", "description": "Whether email is verified", "example": true }, "avatarPath": { "type": "string", "nullable": true, "description": "Path to user avatar image", "example": "/uploads/avatars/user-123.png" }, "createdAt": { "type": "string", "format": "date-time", "description": "Account creation timestamp", "example": "2026-01-15T10:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2026-02-20T14:30:00.000Z" } } }, "Workspace": { "type": "object", "required": [ "id", "name", "email", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Workspace unique identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "maxLength": 255, "description": "Workspace display name", "example": "Acme Corp" }, "slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 255, "description": "URL-friendly workspace identifier", "example": "acme-corp" }, "email": { "type": "string", "format": "email", "description": "Workspace contact email", "example": "contact@acme.com" }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "pending" ], "description": "Workspace status", "example": "active" }, "avatarPath": { "type": "string", "nullable": true, "maxLength": 500, "description": "Path to workspace avatar image", "example": "/uploads/avatars/workspace-123.png" }, "webhookUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Webhook URL for transaction events", "example": "https://acme.com/webhooks/coinbax" }, "walletProvider": { "type": "string", "enum": [ "COINBAX", "CIRCLE", "FIREBLOCKS", "TURNKEY", "UTILA" ], "nullable": true, "description": "Primary wallet provider for this workspace", "example": "TURNKEY" }, "walletId": { "type": "string", "nullable": true, "maxLength": 255, "description": "Wallet identifier from the wallet provider", "example": "wallet_abc123" }, "turnkeyOrganizationId": { "type": "string", "nullable": true, "maxLength": 255, "description": "Turnkey organization ID (if using Turnkey)", "example": "org_turnkey_xyz" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Additional custom metadata (key-value pairs)", "example": { "industry": "fintech", "tier": "enterprise" } }, "billingEnabled": { "type": "boolean", "description": "Whether billing is enabled for this workspace", "example": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Workspace creation timestamp", "example": "2026-01-15T10:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2026-02-20T14:30:00.000Z" } } }, "CreateWorkspaceRequest": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Workspace display name", "example": "Acme Corp" }, "slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 255, "description": "URL-friendly identifier (auto-generated if not provided)", "example": "acme-corp" }, "email": { "type": "string", "format": "email", "description": "Workspace contact email", "example": "contact@acme.com" }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "pending" ], "description": "Initial workspace status", "example": "active" }, "webhookUrl": { "type": "string", "format": "uri", "description": "Webhook URL for transaction events", "example": "https://acme.com/webhooks/coinbax" }, "walletProvider": { "type": "string", "enum": [ "COINBAX", "CIRCLE", "FIREBLOCKS", "TURNKEY", "UTILA" ], "nullable": true, "description": "Wallet provider to use", "example": "TURNKEY" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Custom metadata", "example": { "industry": "fintech" } } } }, "UpdateWorkspaceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Workspace display name", "example": "Acme Corporation" }, "email": { "type": "string", "format": "email", "description": "Workspace contact email", "example": "admin@acme.com" }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "pending" ], "description": "Workspace status" }, "avatarPath": { "type": "string", "maxLength": 500, "nullable": true, "description": "Path to workspace avatar image" }, "webhookUrl": { "type": "string", "format": "uri", "description": "Webhook URL for transaction events" }, "walletProvider": { "type": "string", "enum": [ "COINBAX", "CIRCLE", "FIREBLOCKS", "TURNKEY", "UTILA" ], "nullable": true, "description": "Wallet provider to use" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Custom metadata" } } }, "Customer": { "type": "object", "required": [ "id", "workspaceId", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Customer unique identifier", "example": "550e8400-e29b-41d4-a716-446655440000" }, "workspaceId": { "type": "string", "format": "uuid", "description": "Associated workspace ID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "nullable": true, "maxLength": 255, "description": "External identifier from your system", "example": "cust_12345" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Customer's email address", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "maxLength": 100, "description": "Customer's first name", "example": "John" }, "lastName": { "type": "string", "nullable": true, "maxLength": 100, "description": "Customer's last name", "example": "Doe" }, "phoneNumber": { "type": "string", "nullable": true, "maxLength": 50, "description": "Customer's phone number", "example": "+1-555-123-4567" }, "dateOfBirth": { "type": "string", "format": "date", "nullable": true, "description": "Customer's date of birth", "example": "1990-01-15" }, "address": { "type": "string", "nullable": true, "maxLength": 500, "description": "Customer's street address", "example": "123 Main St" }, "city": { "type": "string", "nullable": true, "maxLength": 100, "description": "Customer's city", "example": "San Francisco" }, "state": { "type": "string", "nullable": true, "maxLength": 100, "description": "Customer's state/province", "example": "CA" }, "postalCode": { "type": "string", "nullable": true, "maxLength": 20, "description": "Customer's postal code", "example": "94102" }, "country": { "type": "string", "nullable": true, "maxLength": 100, "description": "Customer's country", "example": "USA" }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "pending" ], "description": "Customer status", "example": "active" }, "walletAddress": { "type": "string", "nullable": true, "maxLength": 66, "description": "Customer's blockchain wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "emailVerified": { "type": "boolean", "description": "Whether email is verified", "example": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Custom metadata", "example": { "tier": "premium" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Customer creation timestamp", "example": "2026-01-20T08:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2026-02-15T16:45:00.000Z" } } }, "CreateCustomerRequest": { "type": "object", "required": [ "workspaceId", "email", "firstName", "lastName" ], "properties": { "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID to create customer in", "example": "123e4567-e89b-12d3-a456-426614174000" }, "email": { "type": "string", "format": "email", "description": "Customer's email address", "example": "john.doe@example.com" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Customer's first name", "example": "John" }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Customer's last name", "example": "Doe" }, "phoneNumber": { "type": "string", "maxLength": 20, "description": "Customer's phone number", "example": "+1-555-123-4567" }, "dateOfBirth": { "type": "string", "format": "date", "description": "Customer's date of birth", "example": "1990-01-15" }, "address": { "type": "string", "maxLength": 500, "description": "Customer's street address", "example": "123 Main St" }, "city": { "type": "string", "maxLength": 100, "description": "Customer's city", "example": "San Francisco" }, "state": { "type": "string", "maxLength": 100, "description": "Customer's state/province", "example": "CA" }, "postalCode": { "type": "string", "maxLength": 20, "description": "Customer's postal code", "example": "94102" }, "country": { "type": "string", "maxLength": 100, "description": "Customer's country", "example": "USA" }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "pending" ], "description": "Initial customer status", "example": "active" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Custom metadata" } } }, "UpdateCustomerRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Customer's email address" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Customer's first name" }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Customer's last name" }, "phoneNumber": { "type": "string", "maxLength": 20, "description": "Customer's phone number" }, "dateOfBirth": { "type": "string", "format": "date", "description": "Customer's date of birth" }, "address": { "type": "string", "maxLength": 500, "description": "Customer's street address" }, "city": { "type": "string", "maxLength": 100, "description": "Customer's city" }, "state": { "type": "string", "maxLength": 100, "description": "Customer's state/province" }, "postalCode": { "type": "string", "maxLength": 20, "description": "Customer's postal code" }, "country": { "type": "string", "maxLength": 100, "description": "Customer's country" }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "pending" ], "description": "Customer status" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Custom metadata" } } }, "Transaction": { "type": "object", "required": [ "id", "status", "amount", "currency", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Transaction unique identifier", "example": "tx_550e8400-e29b-41d4-a716-446655440000" }, "status": { "type": "string", "enum": [ "PENDING", "ESCROWED", "IN_REVIEW", "COMPLETED", "FAILED", "CANCELLED" ], "description": "Transaction status", "example": "COMPLETED" }, "amount": { "type": "string", "description": "Transaction amount as string", "example": "100.00" }, "currency": { "type": "string", "description": "Transaction currency", "example": "USDC" }, "fromAddress": { "type": "string", "description": "Sender's blockchain address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "toAddress": { "type": "string", "description": "Receiver's blockchain address", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "blockchainNetwork": { "type": "string", "description": "Blockchain network", "example": "base" }, "chainId": { "type": "integer", "description": "Chain ID", "example": 8453 }, "txHash": { "type": "string", "nullable": true, "description": "Blockchain transaction hash", "example": "0xabcd...ef12" }, "orchestrationType": { "type": "string", "enum": [ "raw", "coinbax" ], "description": "Transaction orchestration type", "example": "raw" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Transaction metadata", "example": { "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "customerId": "cust_12345" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Transaction creation timestamp", "example": "2026-02-24T10:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2026-02-24T10:05:00.000Z" }, "_platformName": { "type": "string", "description": "Platform name (for multi-platform queries)", "example": "Main Platform" }, "_platformId": { "type": "string", "description": "Platform ID (for multi-platform queries)", "example": "platform_xyz" } } }, "TransactionStats": { "type": "object", "additionalProperties": { "type": "object", "properties": { "count": { "type": "integer", "description": "Number of transactions in this status", "example": 150 }, "total_amount": { "type": "string", "description": "Total amount for this status", "example": "15000.00" } } }, "example": { "COMPLETED": { "count": 150, "total_amount": "15000.00" }, "PENDING": { "count": 10, "total_amount": "1000.00" }, "ESCROWED": { "count": 5, "total_amount": "500.00" } } }, "CreateWorkspaceTransactionRequest": { "type": "object", "required": [ "fromAddress", "toAddress", "amount", "network" ], "properties": { "fromAddress": { "type": "string", "description": "Sender's blockchain address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "toAddress": { "type": "string", "description": "Receiver's blockchain address", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "amount": { "type": "string", "description": "Transaction amount", "example": "100.00" }, "network": { "type": "string", "description": "Blockchain network (devnet, mainnet-beta, base, ethereum, etc.)", "example": "base" }, "currency": { "type": "string", "description": "Currency to transfer (default USDC)", "example": "USDC" }, "customerId": { "type": "string", "format": "uuid", "description": "Associated customer ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, "orchestrationType": { "type": "string", "enum": [ "raw", "coinbax" ], "description": "Transaction orchestration type (default raw)", "example": "raw" }, "templateId": { "type": "string", "format": "uuid", "description": "Control template ID from coinbax-library", "example": "template_abc123" }, "controlConfigs": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Override configurations for template controls" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Additional transaction metadata", "example": { "note": "Payment for services" } } } }, "WalletAccount": { "type": "object", "properties": { "address": { "type": "string", "description": "Blockchain address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "addressFormat": { "type": "string", "description": "Address format (Turnkey-specific)", "example": "ADDRESS_FORMAT_ETHEREUM" }, "path": { "type": "string", "description": "HD wallet derivation path", "example": "m/44'/60'/0'/0/0" }, "curve": { "type": "string", "description": "Cryptographic curve", "example": "CURVE_SECP256K1" } } }, "WalletAccountsResponse": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/WalletAccount" } }, "message": { "type": "string", "description": "Optional message if no accounts found" } } }, "CreateWalletAccountsRequest": { "type": "object", "required": [ "accounts" ], "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "addressFormat": { "type": "string", "enum": [ "ADDRESS_FORMAT_ETHEREUM", "ADDRESS_FORMAT_SOLANA" ], "description": "Address format for the new account" }, "curve": { "type": "string", "description": "Cryptographic curve" }, "path": { "type": "string", "description": "HD wallet derivation path" } } } } } }, "WalletBalance": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "network": { "type": "string", "description": "Blockchain network", "example": "base" }, "nativeBalance": { "type": "string", "description": "Native token balance", "example": "1.5" }, "nativeSymbol": { "type": "string", "description": "Native token symbol", "example": "ETH" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string", "example": "USDC" }, "balance": { "type": "string", "example": "100.00" }, "contractAddress": { "type": "string", "example": "0x..." } } } } } }, "WalletBalancesResponse": { "type": "object", "properties": { "balances": { "type": "array", "items": { "$ref": "#/components/schemas/WalletBalance" } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal errors during balance fetching" } } }, "InviteUsersRequest": { "type": "object", "required": [ "users" ], "properties": { "users": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "newuser@example.com" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" } } } } } }, "InviteUsersResponse": { "type": "object", "properties": { "invited": { "type": "integer", "description": "Number of successfully invited users", "example": 2 }, "failed": { "type": "integer", "description": "Number of failed invitations", "example": 1 }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "error": { "type": "string" } } } } } }, "WalletProviderConfig": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Config unique identifier" }, "workspaceId": { "type": "string", "format": "uuid", "nullable": true, "description": "Associated workspace ID (null for global configs)" }, "isGlobal": { "type": "boolean", "description": "Whether this is a global config", "example": false }, "providerType": { "type": "string", "enum": [ "TURNKEY", "CIRCLE", "FIREBLOCKS", "UTILA" ], "description": "Wallet provider type", "example": "TURNKEY" }, "providerName": { "type": "string", "description": "Display name for this config", "example": "Main Turnkey Account" }, "walletSetId": { "type": "string", "nullable": true, "description": "Wallet set ID from provider" }, "defaultWalletId": { "type": "string", "nullable": true, "description": "Default wallet ID" }, "isActive": { "type": "boolean", "description": "Whether this config is active", "example": true }, "isDefault": { "type": "boolean", "description": "Whether this is the default config", "example": false }, "supportedNetworks": { "type": "array", "items": { "type": "string" }, "description": "Supported blockchain networks", "example": [ "ethereum", "base", "solana" ] }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateWalletProviderConfigRequest": { "type": "object", "required": [ "workspaceId", "providerType", "providerName", "config" ], "properties": { "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID (required, global configs not allowed)" }, "providerType": { "type": "string", "enum": [ "TURNKEY", "CIRCLE", "FIREBLOCKS", "UTILA" ] }, "providerName": { "type": "string", "example": "Main Turnkey Account" }, "walletSetId": { "type": "string" }, "defaultWalletId": { "type": "string" }, "config": { "type": "object", "description": "Provider-specific credentials (encrypted at rest)", "additionalProperties": true }, "isActive": { "type": "boolean", "default": true }, "isDefault": { "type": "boolean", "default": false }, "supportedNetworks": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true } } }, "Notification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "info", "success", "warning", "error", "transaction", "system" ], "example": "info" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "example": "normal" }, "title": { "type": "string", "example": "New Transaction" }, "message": { "type": "string", "example": "You have a new incoming transaction" }, "isRead": { "type": "boolean", "example": false }, "readAt": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "NotificationsResponse": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } }, "unreadCount": { "type": "integer", "example": 5 } } }, "GlobalSetting": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "description": "Setting key", "example": "coinbax_api_key" }, "value": { "type": "string", "description": "Setting value (empty string if encrypted)", "example": "" }, "category": { "type": "string", "description": "Setting category", "example": "api" }, "description": { "type": "string", "nullable": true, "description": "Setting description" }, "isEncrypted": { "type": "boolean", "description": "Whether the value is encrypted", "example": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateGlobalSettingRequest": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "description": "Unique setting key", "example": "new_setting_key" }, "value": { "type": "string", "description": "Setting value" }, "category": { "type": "string", "description": "Setting category", "example": "general" }, "description": { "type": "string", "description": "Setting description" }, "isEncrypted": { "type": "boolean", "description": "Whether to encrypt the value", "default": false } } }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platformId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/coinbax" }, "eventTypes": { "type": "array", "items": { "type": "string" }, "example": [ "transaction.created", "transaction.completed", "transaction.failed" ] }, "secret": { "type": "string", "description": "Secret for signature verification (only shown on creation)" }, "isActive": { "type": "boolean", "default": true }, "ipWhitelist": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": [ "192.168.1.1", "10.0.0.0/8" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateWebhookSubscriptionRequest": { "type": "object", "required": [ "url", "eventTypes" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL" }, "eventTypes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Event types to subscribe to" }, "ipWhitelist": { "type": "array", "items": { "type": "string" }, "description": "IP addresses allowed to receive webhooks" }, "metadata": { "type": "object", "additionalProperties": true } } }, "UpdateWebhookSubscriptionRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "ipWhitelist": { "type": "array", "items": { "type": "string" }, "nullable": true }, "metadata": { "type": "object", "additionalProperties": true } } }, "WebhookDeliveryLog": { "type": "object", "required": [ "id", "webhookSubscriptionId", "eventType", "deliveryAttempt", "success", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Delivery log ID" }, "webhookSubscriptionId": { "type": "string", "format": "uuid", "description": "Associated webhook subscription ID" }, "eventType": { "type": "string", "description": "Type of event delivered", "example": "transaction.created" }, "eventId": { "type": "string", "format": "uuid", "description": "ID of the event that was delivered" }, "deliveryAttempt": { "type": "integer", "description": "Which delivery attempt this was (1 = first attempt)", "example": 1 }, "success": { "type": "boolean", "description": "Whether the delivery was successful" }, "statusCode": { "type": "integer", "description": "HTTP status code returned by the endpoint", "example": 200, "nullable": true }, "responseTime": { "type": "integer", "description": "Response time in milliseconds", "example": 150, "nullable": true }, "errorMessage": { "type": "string", "description": "Error message if delivery failed", "nullable": true }, "requestHeaders": { "type": "object", "additionalProperties": true, "description": "Headers sent in the request" }, "responseBody": { "type": "string", "description": "Truncated response body (for debugging)", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "OAuthClient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "type": "string", "description": "OAuth client identifier" }, "clientSecret": { "type": "string", "description": "OAuth client secret (only shown on creation)" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "platformId": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "transactions:read", "customers:write" ] }, "grantTypes": { "type": "array", "items": { "type": "string", "enum": [ "authorization_code", "client_credentials", "refresh_token" ] } }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "isActive": { "type": "boolean", "default": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateOAuthClientRequest": { "type": "object", "required": [ "name", "scopes" ], "properties": { "name": { "type": "string", "description": "Display name for the OAuth client" }, "description": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "API scopes this client can access" }, "grantTypes": { "type": "array", "items": { "type": "string", "enum": [ "authorization_code", "client_credentials", "refresh_token" ] }, "default": [ "client_credentials" ] }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } } } }, "UpdateOAuthClientRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the OAuth client" }, "description": { "type": "string", "description": "Description of the client's purpose" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "API scopes this client can access" }, "isActive": { "type": "boolean", "description": "Whether the client is active (deactivating revokes all tokens)" } } }, "OAuthScope": { "type": "object", "required": [ "id", "scope", "resource", "action", "description", "isActive" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Scope unique identifier" }, "scope": { "type": "string", "description": "Scope identifier (e.g., \"transactions:read\")", "example": "transactions:read" }, "resource": { "type": "string", "description": "Resource this scope applies to", "example": "transactions" }, "action": { "type": "string", "description": "Action allowed on the resource", "example": "read" }, "description": { "type": "string", "description": "Human-readable description of what this scope allows", "example": "Read transaction data" }, "isActive": { "type": "boolean", "description": "Whether this scope is currently available", "example": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WorkspaceIntegration": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "integrationId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "inactive", "error" ] }, "errorMessage": { "type": "string", "nullable": true }, "lastValidatedAt": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EnableIntegrationRequest": { "type": "object", "required": [ "integrationId", "config" ], "properties": { "integrationId": { "type": "string", "format": "uuid", "description": "ID of the integration to enable" }, "config": { "type": "object", "additionalProperties": true, "description": "Integration-specific configuration (API keys, etc.)" } } }, "ContractDeployment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "globalTemplateId": { "type": "string", "format": "uuid", "nullable": true }, "network": { "type": "string", "example": "BASE_SEPOLIA" }, "contractType": { "type": "string", "enum": [ "escrow", "factory", "dispute", "custom" ] }, "contractAddress": { "type": "string", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "factoryAddress": { "type": "string", "nullable": true }, "deploymentTxHash": { "type": "string", "nullable": true }, "deployedAt": { "type": "string", "format": "date-time" }, "deployedBy": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "deprecated", "failed" ] }, "isShared": { "type": "boolean" }, "verified": { "type": "boolean" }, "verifiedAt": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "properties": { "gasUsed": { "type": "integer" }, "blockNumber": { "type": "integer" }, "deployerAddress": { "type": "string" }, "factoryVersion": { "type": "string" } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ExternalWalletConfig": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "providerType": { "type": "string", "enum": [ "METAMASK", "WALLET_CONNECT", "COINBASE_WALLET", "LEDGER" ] }, "isEnabled": { "type": "boolean" }, "allowedNetworks": { "type": "array", "items": { "type": "string" }, "example": [ "BASE_SEPOLIA", "ETHEREUM_SEPOLIA" ] }, "allowedTemplateIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "config": { "type": "object", "nullable": true, "properties": { "infuraApiKey": { "type": "string" }, "projectId": { "type": "string" }, "appName": { "type": "string" }, "appLogoUrl": { "type": "string" } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "UpdateExternalWalletConfigRequest": { "type": "object", "properties": { "isEnabled": { "type": "boolean" }, "allowedNetworks": { "type": "array", "items": { "type": "string" } }, "allowedTemplateIds": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "nullable": true, "properties": { "infuraApiKey": { "type": "string" }, "projectId": { "type": "string" }, "appName": { "type": "string" }, "appLogoUrl": { "type": "string" } } } } }, "AuditLog": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "workspaceId": { "type": "string", "format": "uuid", "nullable": true }, "action": { "type": "string", "example": "user.login" }, "resourceType": { "type": "string", "example": "user" }, "resourceId": { "type": "string", "format": "uuid", "nullable": true }, "details": { "type": "string", "nullable": true }, "changes": { "type": "object", "additionalProperties": true, "nullable": true }, "success": { "type": "boolean" }, "errorMessage": { "type": "string", "nullable": true }, "ipAddress": { "type": "string", "nullable": true }, "userAgent": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "CustomerLoginRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 1 } } }, "CustomerRegisterRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8, "maxLength": 100 }, "firstName": { "type": "string", "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 } } }, "CustomerAuthResponse": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "walletAddress": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] } } }, "accessToken": { "type": "string", "description": "JWT access token" }, "refreshToken": { "type": "string", "description": "JWT refresh token" }, "expiresIn": { "type": "integer", "description": "Token expiration in seconds" } } }, "CustomerRefreshTokenRequest": { "type": "object", "required": [ "refreshToken" ], "properties": { "refreshToken": { "type": "string" } } }, "CustomerLinkWalletRequest": { "type": "object", "required": [ "walletAddress", "signature", "message" ], "properties": { "walletAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Ethereum wallet address" }, "signature": { "type": "string", "description": "Signed message proving wallet ownership" }, "message": { "type": "string", "description": "Original message that was signed" } } }, "CustomerProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "walletAddress": { "type": "string", "nullable": true }, "walletLinkedAt": { "type": "string", "format": "date-time", "nullable": true }, "emailVerified": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] } } } }, "responses": { "BadRequest": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "statusCode": 400, "details": { "email": "Invalid email format" } }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "Unauthorized": { "description": "Unauthorized - missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "UNAUTHORIZED", "message": "Authentication required", "statusCode": 401 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "Forbidden": { "description": "Forbidden - insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "FORBIDDEN", "message": "You do not have permission to access this resource", "statusCode": 403 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "NOT_FOUND", "message": "Resource not found", "statusCode": 404 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "Conflict": { "description": "Conflict - resource already exists or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "CONFLICT", "message": "Resource already exists", "statusCode": 409 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "RateLimited": { "description": "Too many requests - rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until rate limit resets", "example": 42 }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit ceiling", "example": 100 }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in window", "example": 0 }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when limit resets", "example": 1735073400 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests, please try again later", "statusCode": 429 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "ServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred", "statusCode": 500 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "paths": { "/health": { "get": { "summary": "Health check", "description": "Returns the health status of the API", "operationId": "healthCheck", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "example": "healthy" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string", "example": "1.0.0" } } } } } ] }, "example": { "success": true, "data": { "status": "healthy", "timestamp": "2026-02-24T12:00:00.000Z", "version": "1.0.0" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/auth/login": { "post": { "summary": "User login", "description": "Authenticate a user with email and password. Returns access token and refresh token.\n\nThe access token expires in 1 hour, refresh token in 7 days.\n", "operationId": "authLogin", "tags": [ "Authentication" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "description": "User's email address", "example": "admin@coinbax.com" }, "password": { "type": "string", "format": "password", "minLength": 8, "description": "User's password (min 8 characters)", "example": "admin123" } } } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "accessToken": { "type": "string", "description": "JWT access token (expires in 1 hour)" }, "refreshToken": { "type": "string", "description": "JWT refresh token (expires in 7 days)" }, "expiresIn": { "type": "integer", "description": "Access token expiration in seconds", "example": 3600 } } } } } ] }, "example": { "success": true, "data": { "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "admin@coinbax.com", "firstName": "Admin", "lastName": "User", "role": "ADMIN", "workspaceId": "123e4567-e89b-12d3-a456-426614174000" }, "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresIn": 3600 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INVALID_CREDENTIALS", "message": "Invalid email or password", "statusCode": 401 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/auth/register": { "post": { "summary": "Register new user", "description": "Register a new user account. A verification email will be sent.\n\n**Note:** Registration may be disabled in some deployments.\n", "operationId": "authRegister", "tags": [ "Authentication" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password", "firstName", "lastName" ], "properties": { "email": { "type": "string", "format": "email", "description": "User's email address", "example": "newuser@example.com" }, "password": { "type": "string", "format": "password", "minLength": 8, "description": "User's password (min 8 characters)" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "User's first name", "example": "John" }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "User's last name", "example": "Doe" }, "workspaceName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Workspace name (optional, creates new workspace)", "example": "Acme Corp" } } } } } }, "responses": { "201": { "description": "Registration successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "message": { "type": "string", "example": "Verification email sent" } } } } } ] }, "example": { "success": true, "data": { "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "newuser@example.com", "firstName": "John", "lastName": "Doe", "role": "CLIENT", "emailVerified": false }, "message": "Verification email sent" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "description": "Email already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "EMAIL_EXISTS", "message": "A user with this email already exists", "statusCode": 409 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/auth/me": { "get": { "summary": "Get current user", "description": "Returns the currently authenticated user's profile information", "operationId": "authMe", "tags": [ "Authentication" ], "responses": { "200": { "description": "Current user profile", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } } } ] }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "admin@coinbax.com", "firstName": "Admin", "lastName": "User", "role": "ADMIN", "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "emailVerified": true, "avatarPath": "/uploads/avatars/user-123.png", "createdAt": "2026-01-15T10:00:00.000Z", "updatedAt": "2026-02-20T14:30:00.000Z" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/auth/refresh": { "post": { "summary": "Refresh access token", "description": "Exchange a refresh token for a new access token.\n\nThe refresh token is single-use and a new refresh token is returned.\n", "operationId": "authRefresh", "tags": [ "Authentication" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refreshToken" ], "properties": { "refreshToken": { "type": "string", "description": "The refresh token from login or previous refresh" } } } } } }, "responses": { "200": { "description": "Token refreshed successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "New JWT access token" }, "refreshToken": { "type": "string", "description": "New JWT refresh token" }, "expiresIn": { "type": "integer", "description": "Access token expiration in seconds", "example": 3600 } } } } } ] } } } }, "401": { "description": "Invalid or expired refresh token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "INVALID_REFRESH_TOKEN", "message": "Refresh token is invalid or expired", "statusCode": 401 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/auth/logout": { "post": { "summary": "Logout user", "description": "Invalidate the current session and refresh token.\n\nThe access token will remain valid until expiration, but the refresh token\nwill be immediately invalidated.\n", "operationId": "authLogout", "tags": [ "Authentication" ], "responses": { "200": { "description": "Logout successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Logged out successfully" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces": { "get": { "summary": "List all workspaces", "description": "Retrieve a paginated list of all workspaces.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "listWorkspaces", "tags": [ "Workspaces" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number (1-indexed)", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 } ], "responses": { "200": { "description": "Workspaces list retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } ] }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Acme Corp", "slug": "acme-corp", "email": "contact@acme.com", "status": "active", "walletProvider": "TURNKEY", "createdAt": "2026-01-15T10:00:00.000Z", "updatedAt": "2026-02-20T14:30:00.000Z" } ], "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000", "pagination": { "page": 1, "limit": 20, "total": 50, "totalPages": 3 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create a new workspace", "description": "Create a new workspace (tenant) in the system.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "createWorkspace", "tags": [ "Workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceRequest" }, "example": { "name": "Acme Corp", "email": "contact@acme.com", "walletProvider": "TURNKEY", "metadata": { "industry": "fintech" } } } } }, "responses": { "201": { "description": "Workspace created successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } ] }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Acme Corp", "slug": "acme-corp", "email": "contact@acme.com", "status": "pending", "walletProvider": "TURNKEY", "metadata": { "industry": "fintech" }, "createdAt": "2026-02-24T12:00:00.000Z", "updatedAt": "2026-02-24T12:00:00.000Z" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Workspace with this slug already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "CONFLICT", "message": "A workspace with this slug already exists", "statusCode": 409 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/me": { "get": { "summary": "Get current user's workspace", "description": "Retrieve the workspace associated with the currently authenticated user.\n", "operationId": "getMyWorkspace", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Workspace retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } ] }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Acme Corp", "slug": "acme-corp", "email": "contact@acme.com", "status": "active", "walletProvider": "TURNKEY", "createdAt": "2026-01-15T10:00:00.000Z", "updatedAt": "2026-02-20T14:30:00.000Z" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "description": "User has no associated workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "BAD_REQUEST", "message": "Client ID not found for this user", "statusCode": 400 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "summary": "Update current user's workspace", "description": "Update the workspace associated with the currently authenticated user.\n\nAllows workspace members to update their own organization details.\n", "operationId": "updateMyWorkspace", "tags": [ "Workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceRequest" }, "example": { "name": "Acme Corporation", "email": "admin@acme.com", "webhookUrl": "https://acme.com/webhooks/coinbax-v2" } } } }, "responses": { "200": { "description": "Workspace updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}": { "get": { "summary": "Get workspace by ID", "description": "Retrieve a workspace by its unique identifier.\n\n**Permissions:**\n- User must be a member of the workspace OR\n- User must be ADMIN or SUPER_ADMIN\n", "operationId": "getWorkspace", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace UUID", "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "Workspace found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } ] }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Acme Corp", "slug": "acme-corp", "email": "contact@acme.com", "status": "active", "walletProvider": "TURNKEY", "webhookUrl": "https://acme.com/webhooks/coinbax", "createdAt": "2026-01-15T10:00:00.000Z", "updatedAt": "2026-02-20T14:30:00.000Z" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Access denied - not a member of this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "error": { "code": "FORBIDDEN", "message": "You do not have access to this workspace", "statusCode": 403 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "summary": "Update workspace", "description": "Update workspace details.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "updateWorkspace", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceRequest" }, "example": { "name": "Acme Corporation", "email": "admin@acme.com", "webhookUrl": "https://acme.com/webhooks/coinbax-v2" } } } }, "responses": { "200": { "description": "Workspace updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete workspace", "description": "Permanently delete a workspace.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n\n**Warning:** This action is irreversible and will delete all associated data.\n", "operationId": "deleteWorkspace", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Workspace deleted successfully (no content)" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/customers": { "get": { "summary": "List workspace customers", "description": "Retrieve a paginated list of customers belonging to a specific workspace.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "listWorkspaceCustomers", "tags": [ "Workspace Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "description": "Filter by customer status", "schema": { "type": "string", "enum": [ "active", "inactive", "suspended", "pending" ] } }, { "name": "search", "in": "query", "description": "Search by name or email", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customers list retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } ] }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "status": "active", "createdAt": "2026-01-20T08:30:00.000Z", "updatedAt": "2026-02-15T16:45:00.000Z" } ], "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000", "pagination": { "page": 1, "limit": 20, "total": 100, "totalPages": 5 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create customer in workspace", "description": "Create a new customer within a specific workspace.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "createWorkspaceCustomer", "tags": [ "Workspace Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "firstName", "lastName" ], "properties": { "email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "phoneNumber": { "type": "string", "example": "+1-555-123-4567" }, "address": { "type": "string", "example": "123 Main St" }, "city": { "type": "string", "example": "San Francisco" }, "state": { "type": "string", "example": "CA" }, "postalCode": { "type": "string", "example": "94102" }, "country": { "type": "string", "example": "USA" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Customer created successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } ] }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "status": "active", "createdAt": "2026-02-24T12:00:00.000Z", "updatedAt": "2026-02-24T12:00:00.000Z" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/transactions": { "get": { "summary": "List workspace transactions", "description": "Retrieve transactions for a specific workspace. Transactions are aggregated from:\n1. Platform mappings (external wallet platforms like Transmitter)\n2. Turnkey wallet addresses (for admin-managed wallets)\n3. Metadata wallet addresses (fallback)\n", "operationId": "listWorkspaceTransactions", "tags": [ "Workspace Transactions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "status", "in": "query", "description": "Filter by transaction status", "schema": { "type": "string", "enum": [ "PENDING", "ESCROWED", "IN_REVIEW", "COMPLETED", "FAILED", "CANCELLED" ] } }, { "name": "dateFrom", "in": "query", "description": "Start date filter (ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, { "name": "dateTo", "in": "query", "description": "End date filter (ISO 8601)", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Transactions list retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } ] }, "example": { "success": true, "data": { "transactions": [ { "id": "tx_550e8400-e29b-41d4-a716-446655440000", "status": "COMPLETED", "amount": "100.00", "currency": "USDC", "fromAddress": "0x1234567890abcdef1234567890abcdef12345678", "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12", "blockchainNetwork": "base", "createdAt": "2026-02-24T10:00:00.000Z", "_platformName": "Main Platform" } ], "pagination": { "total": 150, "page": 1, "limit": 100, "totalPages": 2 } }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create transaction in workspace", "description": "Create a new blockchain transaction for a workspace.\n\nThe transaction is proxied to coinbax-api which handles actual blockchain execution.\n", "operationId": "createWorkspaceTransaction", "tags": [ "Workspace Transactions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceTransactionRequest" }, "example": { "fromAddress": "0x1234567890abcdef1234567890abcdef12345678", "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12", "amount": "100.00", "network": "base", "currency": "USDC", "orchestrationType": "raw", "metadata": { "note": "Payment for services" } } } } }, "responses": { "200": { "description": "Transaction created successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "transaction": { "$ref": "#/components/schemas/Transaction" } } } } } ] }, "example": { "success": true, "data": { "transaction": { "id": "tx_550e8400-e29b-41d4-a716-446655440000", "status": "PENDING", "amount": "100.00", "currency": "USDC", "fromAddress": "0x1234567890abcdef1234567890abcdef12345678", "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12", "blockchainNetwork": "base", "orchestrationType": "raw", "createdAt": "2026-02-24T12:00:00.000Z" } }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/transactions/{txId}": { "get": { "summary": "Get transaction by ID", "description": "Fetch a single transaction by ID from coinbax-api.\nProxies the request to coinbax-api using the platform's API key.\n\n**Authentication:** X-API-Key header with workspace API key\n", "operationId": "getWorkspaceTransaction", "tags": [ "Workspace Transactions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "txId", "in": "path", "required": true, "description": "Transaction UUID", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Transaction retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/transactions/{txId}/submit-escrow-hash": { "post": { "summary": "Submit escrow transaction hash", "description": "Submit the escrow deposit transaction hash for a pending transaction.\nThis confirms that funds have been deposited into the escrow contract.\n\n**Authentication:** X-API-Key header with workspace API key\n", "operationId": "submitEscrowHash", "tags": [ "Workspace Transactions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "txId", "in": "path", "required": true, "description": "Transaction UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transactionHash" ], "properties": { "transactionHash": { "type": "string", "description": "The blockchain transaction hash of the escrow deposit", "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" } } } } } }, "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Escrow hash submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Escrow transaction hash submitted successfully" }, "transaction": { "$ref": "#/components/schemas/Transaction" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/customers": { "get": { "summary": "List all customers", "description": "Retrieve a paginated list of all customers across workspaces.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "listCustomers", "tags": [ "Customers" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number (1-indexed)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "workspaceId", "in": "query", "description": "Filter by workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by customer status", "schema": { "type": "string", "enum": [ "active", "inactive", "suspended", "pending" ] } }, { "name": "search", "in": "query", "description": "Search by name or email", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customers list retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } ] }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "status": "active", "createdAt": "2026-01-20T08:30:00.000Z", "updatedAt": "2026-02-15T16:45:00.000Z" } ], "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000", "pagination": { "page": 1, "limit": 20, "total": 500, "totalPages": 25 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create a new customer", "description": "Create a new customer in a specified workspace.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "createCustomer", "tags": [ "Customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" }, "example": { "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "phoneNumber": "+1-555-123-4567", "address": "123 Main St", "city": "San Francisco", "state": "CA", "postalCode": "94102", "country": "USA" } } } }, "responses": { "201": { "description": "Customer created successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } ] }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "status": "active", "createdAt": "2026-02-24T12:00:00.000Z", "updatedAt": "2026-02-24T12:00:00.000Z" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/customers/{id}": { "get": { "summary": "Get customer by ID", "description": "Retrieve a customer by their unique identifier.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "getCustomer", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Customer found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } ] }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "phoneNumber": "+1-555-123-4567", "status": "active", "walletAddress": "0x1234567890abcdef1234567890abcdef12345678", "emailVerified": true, "createdAt": "2026-01-20T08:30:00.000Z", "updatedAt": "2026-02-15T16:45:00.000Z" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "summary": "Update customer", "description": "Update customer details.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "updateCustomer", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerRequest" }, "example": { "firstName": "Jonathan", "lastName": "Doe", "phoneNumber": "+1-555-987-6543", "status": "active" } } } }, "responses": { "200": { "description": "Customer updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete customer", "description": "Permanently delete a customer.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n\n**Warning:** This action is irreversible.\n", "operationId": "deleteCustomer", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Customer deleted successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Customer deleted successfully" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/customers/{id}/circle-wallet": { "get": { "summary": "Get customer Circle wallet", "description": "Get the Circle wallet information for a customer.\nReturns the wallet address and ID if the customer has a Circle wallet.\n\n**Permissions:** Requires workspace access to the customer's workspace\n", "operationId": "getCustomerCircleWallet", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Circle wallet information", "content": { "application/json": { "schema": { "type": "object", "properties": { "hasWallet": { "type": "boolean", "description": "Whether the customer has a Circle wallet" }, "walletId": { "type": "string", "description": "Circle wallet ID" }, "walletAddress": { "type": "string", "description": "Blockchain wallet address" }, "walletLinkedAt": { "type": "string", "format": "date-time", "description": "When the wallet was linked" } } }, "examples": { "with_wallet": { "summary": "Customer with wallet", "value": { "hasWallet": true, "walletId": "wallet-id-123", "walletAddress": "0x1234567890abcdef1234567890abcdef12345678", "walletLinkedAt": "2026-02-20T10:00:00.000Z" } }, "without_wallet": { "summary": "Customer without wallet", "value": { "hasWallet": false, "message": "Customer does not have a Circle wallet provisioned" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Provision Circle wallet for customer", "description": "Provision a Circle wallet for a customer.\nCreates a new wallet in the workspace's Circle wallet set.\n\n**Prerequisites:**\n- Workspace must have a Circle wallet provider configured\n- Customer must not already have a Circle wallet\n\n**Permissions:** Requires workspace access\n", "operationId": "createCustomerCircleWallet", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "string", "default": "BASE_SEPOLIA", "description": "Blockchain network for the wallet", "enum": [ "BASE_SEPOLIA", "BASE", "ETH_SEPOLIA", "ETH" ] } } } } } }, "responses": { "201": { "description": "Circle wallet created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "walletId": { "type": "string" }, "walletAddress": { "type": "string" }, "blockchain": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Bad request (customer already has wallet, workspace not configured)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/customers/{id}/circle-wallet/balance": { "get": { "summary": "Get customer Circle wallet balance", "description": "Get the token balance for a customer's Circle wallet.\n\n**Permissions:** Requires workspace access to the customer's workspace\n", "operationId": "getCustomerCircleWalletBalance", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Wallet balance retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "balances": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "example": "USDC" }, "balance": { "type": "string", "example": "100.50" }, "network": { "type": "string", "example": "BASE_SEPOLIA" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/customers/{id}/transactions": { "get": { "summary": "Get customer transactions", "description": "Retrieve transactions for a specific customer.\n\n**Permissions:** Requires workspace access to the customer's workspace\n", "operationId": "getCustomerTransactions", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Customer transactions retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/transactions": { "get": { "summary": "List transactions", "description": "Retrieve a paginated list of transactions. Transactions are aggregated from all\nconnected platforms (via platform mappings) or from the global API key.\n\n**Filtering:**\n- Filter by status, date range, addresses, wallet address\n\n**Pagination:**\n- Default: 20 items per page\n- Max: 100 items per page\n", "operationId": "listTransactions", "tags": [ "Transactions" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number (1-indexed)", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 }, { "name": "status", "in": "query", "description": "Filter by transaction status", "schema": { "type": "string", "enum": [ "PENDING", "ESCROWED", "IN_REVIEW", "COMPLETED", "FAILED", "CANCELLED" ] }, "example": "COMPLETED" }, { "name": "dateFrom", "in": "query", "description": "Start date filter (ISO 8601)", "schema": { "type": "string", "format": "date-time" }, "example": "2026-02-01T00:00:00Z" }, { "name": "dateTo", "in": "query", "description": "End date filter (ISO 8601)", "schema": { "type": "string", "format": "date-time" }, "example": "2026-02-24T23:59:59Z" }, { "name": "fromAddress", "in": "query", "description": "Filter by sender wallet address", "schema": { "type": "string" }, "example": "0x1234567890abcdef1234567890abcdef12345678" }, { "name": "toAddress", "in": "query", "description": "Filter by receiver wallet address", "schema": { "type": "string" }, "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, { "name": "walletAddress", "in": "query", "description": "Filter by either sender or receiver address", "schema": { "type": "string" }, "example": "0x1234567890abcdef1234567890abcdef12345678" } ], "responses": { "200": { "description": "Transaction list retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "example": 150 }, "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 20 }, "totalPages": { "type": "integer", "example": 8 }, "platformCount": { "type": "integer", "description": "Number of platforms queried", "example": 3 } } } } } } } ] }, "example": { "success": true, "data": { "data": [ { "id": "tx_abc123", "status": "COMPLETED", "amount": "100.00", "currency": "USDC", "fromAddress": "0x1234567890abcdef1234567890abcdef12345678", "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12", "blockchainNetwork": "base", "chainId": 8453, "txHash": "0xabcd...ef12", "createdAt": "2026-02-24T10:00:00.000Z", "_platformName": "Main Platform", "_platformId": "platform_xyz" } ], "meta": { "total": 150, "page": 1, "limit": 20, "totalPages": 8, "platformCount": 3 } }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/transactions/{id}": { "get": { "summary": "Get transaction by ID", "description": "Retrieve a transaction by its unique identifier.\n\nThe transaction is searched across all connected platforms.\n", "operationId": "getTransaction", "tags": [ "Transactions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Transaction UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transaction found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transaction" } } } ] }, "example": { "success": true, "data": { "id": "tx_550e8400-e29b-41d4-a716-446655440000", "status": "COMPLETED", "amount": "100.00", "currency": "USDC", "fromAddress": "0x1234567890abcdef1234567890abcdef12345678", "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12", "blockchainNetwork": "base", "chainId": 8453, "txHash": "0xabcdef1234567890abcdef1234567890abcdef12345678901234567890abcdef12", "orchestrationType": "raw", "metadata": { "workspaceId": "123e4567-e89b-12d3-a456-426614174000" }, "createdAt": "2026-02-24T10:00:00.000Z", "updatedAt": "2026-02-24T10:05:00.000Z", "_platformName": "Main Platform", "_platformId": "platform_xyz" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/transactions/stats": { "get": { "summary": "Get transaction statistics", "description": "Retrieve aggregated transaction statistics across all connected platforms.\n\nReturns counts and totals grouped by transaction status.\n", "operationId": "getTransactionStats", "tags": [ "Transactions" ], "responses": { "200": { "description": "Transaction statistics retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TransactionStats" } } } ] }, "example": { "success": true, "data": { "COMPLETED": { "count": 1500, "total_amount": "150000.00" }, "PENDING": { "count": 25, "total_amount": "2500.00" }, "ESCROWED": { "count": 10, "total_amount": "1000.00" }, "IN_REVIEW": { "count": 5, "total_amount": "500.00" }, "FAILED": { "count": 15, "total_amount": "1500.00" }, "CANCELLED": { "count": 8, "total_amount": "800.00" } }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/users": { "get": { "summary": "List workspace users", "description": "Retrieve a paginated list of users belonging to a specific workspace.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "listWorkspaceUsers", "tags": [ "Workspace Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Users list retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/me/invite-users": { "post": { "summary": "Invite users to workspace", "description": "Invite team members to the authenticated user's workspace organization.\nCreates user accounts and sends invitation emails with temporary passwords.\n", "operationId": "inviteWorkspaceUsers", "tags": [ "Workspace Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUsersRequest" }, "example": { "users": [ { "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe" }, { "email": "jane.smith@example.com", "firstName": "Jane", "lastName": "Smith" } ] } } } }, "responses": { "200": { "description": "Invitation batch processed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InviteUsersResponse" } } } ] }, "example": { "success": true, "data": { "invited": 2, "failed": 0, "users": [ { "id": "uuid-1", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe" }, { "id": "uuid-2", "email": "jane.smith@example.com", "firstName": "Jane", "lastName": "Smith" } ] }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/wallet-accounts": { "get": { "summary": "List wallet accounts", "description": "Retrieve wallet accounts for a workspace from its configured wallet provider (Turnkey).\n", "operationId": "listWorkspaceWalletAccounts", "tags": [ "Workspace Wallets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Wallet accounts retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalletAccountsResponse" } } } ] } } } }, "400": { "description": "Wallet provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create wallet accounts", "description": "Create new wallet accounts for a workspace in its configured wallet provider (Turnkey).\n", "operationId": "createWorkspaceWalletAccounts", "tags": [ "Workspace Wallets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletAccountsRequest" } } } }, "responses": { "200": { "description": "Wallet accounts created successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalletAccountsResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/wallet-balances": { "get": { "summary": "Get wallet balances", "description": "Retrieve blockchain balances for all wallet accounts in a workspace.\nFetches balances from both Solana and EVM networks with graceful degradation.\n", "operationId": "getWorkspaceWalletBalances", "tags": [ "Workspace Wallets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Wallet balances retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalletBalancesResponse" } } } ] }, "example": { "success": true, "data": { "balances": [ { "address": "0x1234...", "network": "base", "nativeBalance": "0.5", "nativeSymbol": "ETH", "tokens": [ { "symbol": "USDC", "balance": "100.00", "contractAddress": "0xusdc..." } ] } ], "warnings": [] }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "description": "Wallet provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users": { "get": { "summary": "List all users", "description": "Retrieve a paginated list of all users across workspaces.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "listUsers", "tags": [ "Users" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "workspaceId", "in": "query", "description": "Filter by workspace", "schema": { "type": "string", "format": "uuid" } }, { "name": "role", "in": "query", "description": "Filter by role", "schema": { "type": "string", "enum": [ "admin", "client" ] } }, { "name": "status", "in": "query", "description": "Filter by status", "schema": { "type": "string", "enum": [ "active", "inactive", "suspended" ] } }, { "name": "search", "in": "query", "description": "Search by name or email", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Users list retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create a new user", "description": "Create a new user account.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "createUser", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password", "role" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 6 }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "client" ] }, "workspaceId": { "type": "string", "format": "uuid" } } }, "example": { "email": "newuser@example.com", "password": "securePassword123", "firstName": "New", "lastName": "User", "role": "client", "workspaceId": "123e4567-e89b-12d3-a456-426614174000" } } } }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "User with this email already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/me": { "get": { "summary": "Get current user profile", "description": "Retrieve the authenticated user's full profile information including workspace.\n", "operationId": "getCurrentUser", "tags": [ "Users" ], "responses": { "200": { "description": "User profile retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "summary": "Update current user profile", "description": "Update the authenticated user's profile information.\nOnly firstName and lastName can be updated.\n", "operationId": "updateCurrentUser", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 } } }, "example": { "firstName": "Updated", "lastName": "Name" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{id}": { "get": { "summary": "Get user by ID", "description": "Retrieve a user by their unique identifier.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "getUser", "tags": [ "Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "User found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "summary": "Update user", "description": "Update user details.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "updateUser", "tags": [ "Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 6 }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "client" ] }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended" ] }, "workspaceId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete user", "description": "Permanently delete a user.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "deleteUser", "tags": [ "Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "example": "User deleted successfully" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/wallet-provider-configs": { "get": { "summary": "List wallet provider configurations", "description": "Retrieve all wallet provider configurations.\nEncrypted config values are never returned for security.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "listWalletProviderConfigs", "tags": [ "Wallet Provider Configs" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "isGlobal", "in": "query", "schema": { "type": "boolean" } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "providerType", "in": "query", "schema": { "type": "string", "enum": [ "TURNKEY", "CIRCLE", "FIREBLOCKS", "UTILA" ] } }, { "name": "isActive", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Configurations retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WalletProviderConfig" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create wallet provider configuration", "description": "Create a new wallet provider configuration.\nGlobal configs are not allowed - each workspace must configure its own provider.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "createWalletProviderConfig", "tags": [ "Wallet Provider Configs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletProviderConfigRequest" }, "example": { "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "providerType": "TURNKEY", "providerName": "Main Turnkey Account", "config": { "organizationId": "org_123", "apiPublicKey": "pk_...", "apiPrivateKey": "sk_..." }, "supportedNetworks": [ "ethereum", "base" ] } } } }, "responses": { "201": { "description": "Configuration created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletProviderConfig" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/wallet-provider-configs/{id}": { "get": { "summary": "Get wallet provider configuration", "description": "Retrieve a specific wallet provider configuration.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "getWalletProviderConfig", "tags": [ "Wallet Provider Configs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Configuration found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletProviderConfig" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "summary": "Update wallet provider configuration", "description": "Update a wallet provider configuration.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "updateWalletProviderConfig", "tags": [ "Wallet Provider Configs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerName": { "type": "string" }, "config": { "type": "object", "additionalProperties": true }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "supportedNetworks": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Configuration updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletProviderConfig" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete wallet provider configuration", "description": "Delete a wallet provider configuration.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "deleteWalletProviderConfig", "tags": [ "Wallet Provider Configs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Configuration deleted successfully" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/wallet-provider-configs/{id}/test-connection": { "post": { "summary": "Test wallet provider connection", "description": "Test the connection to a wallet provider using the stored configuration.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "testWalletProviderConnection", "tags": [ "Wallet Provider Configs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Connection test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/wallet-provider-configs/status": { "get": { "summary": "Get wallet provider config status", "description": "Returns the status and version of all active wallet provider configs.\nThis endpoint is used by coinbax-api for cache invalidation.\n\n**Authentication:** X-Internal-API-Key header (internal service-to-service calls only)\n", "operationId": "getWalletProviderConfigStatus", "tags": [ "Wallet Provider Configs" ], "security": [ { "internalApiKey": [] } ], "responses": { "200": { "description": "Configuration status retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "configs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid", "nullable": true }, "isGlobal": { "type": "boolean" }, "providerType": { "type": "string" }, "providerName": { "type": "string" }, "version": { "type": "integer" }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/wallet-provider-configs/check-duplicate": { "get": { "summary": "Check for duplicate wallet provider config", "description": "Check if a wallet provider config with the same provider type exists.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "checkDuplicateWalletProviderConfig", "tags": [ "Wallet Provider Configs" ], "parameters": [ { "name": "providerType", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "CIRCLE", "TURNKEY" ] } }, { "name": "workspaceId", "in": "query", "schema": { "type": "string", "format": "uuid", "description": "Check within specific workspace" } }, { "name": "excludeId", "in": "query", "schema": { "type": "string", "format": "uuid", "description": "Exclude this config ID from check" } } ], "responses": { "200": { "description": "Duplicate check result", "content": { "application/json": { "schema": { "type": "object", "properties": { "isDuplicate": { "type": "boolean" }, "existingConfig": { "$ref": "#/components/schemas/WalletProviderConfig" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/wallet-provider-configs/{id}/set-default": { "post": { "summary": "Set wallet provider config as default", "description": "Set a wallet provider configuration as the default for its scope.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "setDefaultWalletProviderConfig", "tags": [ "Wallet Provider Configs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Config set as default successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalletProviderConfig" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/wallet-provider-configs/effective": { "get": { "summary": "Get effective wallet provider configuration", "description": "Get the effective (currently active) wallet provider configuration.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "getEffectiveWalletProviderConfig", "tags": [ "Wallet Provider Configs" ], "parameters": [ { "name": "workspaceId", "in": "query", "description": "Workspace to get effective config for", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Effective configuration found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletProviderConfig" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No effective configuration found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/notifications": { "get": { "summary": "List notifications", "description": "Retrieve notifications for the authenticated user.\n", "operationId": "listNotifications", "tags": [ "Notifications" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "unread", "in": "query", "description": "Only return unread notifications", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Notifications retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NotificationsResponse" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } ] }, "example": { "success": true, "data": { "notifications": [ { "id": "notif-uuid-1", "userId": "user-uuid", "type": "transaction", "priority": "normal", "title": "New Transaction", "message": "You received 100 USDC", "isRead": false, "createdAt": "2026-02-24T10:00:00.000Z" } ], "unreadCount": 5 }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000", "pagination": { "page": 1, "limit": 20, "total": 50, "totalPages": 3 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete all notifications", "description": "Delete all notifications for the authenticated user.\n", "operationId": "deleteAllNotifications", "tags": [ "Notifications" ], "responses": { "200": { "description": "All notifications deleted", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "example": "All notifications deleted successfully" }, "count": { "type": "integer", "example": 25 } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/notifications/{id}/read": { "patch": { "summary": "Mark notification as read", "description": "Mark a specific notification as read.\n", "operationId": "markNotificationAsRead", "tags": [ "Notifications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Notification marked as read", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Notification" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/notifications/mark-all-read": { "post": { "summary": "Mark all notifications as read", "description": "Mark all notifications as read for the authenticated user.\n", "operationId": "markAllNotificationsAsRead", "tags": [ "Notifications" ], "responses": { "200": { "description": "All notifications marked as read", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "example": "All notifications marked as read" }, "count": { "type": "integer", "example": 10 } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/settings": { "get": { "summary": "List global settings", "description": "Retrieve global settings. Encrypted values are returned as empty strings.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "listSettings", "tags": [ "Settings" ], "parameters": [ { "name": "category", "in": "query", "description": "Filter by category", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Settings retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "settings": { "type": "array", "items": { "$ref": "#/components/schemas/GlobalSetting" } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create or update global setting", "description": "Create a new global setting or update an existing one.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "createSetting", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGlobalSettingRequest" }, "example": { "key": "custom_setting", "value": "setting_value", "category": "general", "description": "A custom setting", "isEncrypted": false } } } }, "responses": { "201": { "description": "Setting created successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GlobalSetting" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/webhooks": { "get": { "summary": "List webhook subscriptions", "description": "Get all webhook subscriptions for a workspace.\n\n**Requires:** Workspace access\n", "operationId": "listWorkspaceWebhooks", "tags": [ "Workspace Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "isActive", "in": "query", "description": "Filter by active status", "schema": { "type": "boolean" } }, { "name": "eventType", "in": "query", "description": "Filter by event type", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook subscriptions retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create webhook subscription", "description": "Create a new webhook subscription for a workspace.\n\n**Requires:** Workspace access\n", "operationId": "createWorkspaceWebhook", "tags": [ "Workspace Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookSubscriptionRequest" }, "example": { "url": "https://example.com/webhooks/coinbax", "eventTypes": [ "transaction.created", "transaction.completed" ], "ipWhitelist": [ "192.168.1.1" ] } } } }, "responses": { "201": { "description": "Webhook subscription created successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/webhooks/{webhookId}": { "get": { "summary": "Get webhook subscription", "description": "Get details of a specific webhook subscription.\n\n**Requires:** Workspace access\n", "operationId": "getWorkspaceWebhook", "tags": [ "Workspace Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook subscription retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "summary": "Update webhook subscription", "description": "Update a webhook subscription.\n\n**Requires:** Workspace access\n", "operationId": "updateWorkspaceWebhook", "tags": [ "Workspace Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookSubscriptionRequest" } } } }, "responses": { "200": { "description": "Webhook subscription updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete webhook subscription", "description": "Delete a webhook subscription.\n\n**Requires:** Workspace access\n", "operationId": "deleteWorkspaceWebhook", "tags": [ "Workspace Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook subscription deleted successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Subscription deleted" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/webhooks/{webhookId}/delivery-logs": { "get": { "summary": "Get webhook delivery logs", "description": "Get delivery logs for a webhook subscription.\n\n**Requires:** Workspace access\n\nLogs are retained for 30 days. Useful for debugging delivery issues.\n", "operationId": "getWorkspaceWebhookDeliveryLogs", "tags": [ "Workspace Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of logs to return (default 20)", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Offset for pagination", "schema": { "type": "integer", "default": 0 } }, { "name": "successOnly", "in": "query", "description": "Only return successful deliveries", "schema": { "type": "boolean" } }, { "name": "failuresOnly", "in": "query", "description": "Only return failed deliveries", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Delivery logs retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryLog" } }, "total": { "type": "integer", "example": 150 } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/webhooks/{webhookId}/rotate-secret": { "post": { "summary": "Initiate secret rotation", "description": "Start the secret rotation process for a webhook.\n\n**Requires:** Workspace access\n\n**Zero-Downtime Rotation:**\n1. Call this endpoint to get a new secret\n2. Update your webhook handler to accept both old and new secrets\n3. Call `/complete-rotation` to finalize\n\nThe old secret remains valid until rotation is completed.\n", "operationId": "rotateWorkspaceWebhookSecret", "tags": [ "Workspace Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Secret rotation initiated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "newSecret": { "type": "string", "description": "New webhook secret (shown only once)", "example": "whsec_newABC123..." }, "rotationExpiresAt": { "type": "string", "format": "date-time", "description": "When the rotation window expires", "example": "2026-02-27T12:00:00Z" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/webhooks/{webhookId}/complete-rotation": { "post": { "summary": "Complete secret rotation", "description": "Complete the secret rotation process.\n\n**Requires:** Workspace access\n\nAfter calling this, only the new secret will be valid.\nMake sure your webhook handler has been updated first.\n", "operationId": "completeWorkspaceWebhookRotation", "tags": [ "Workspace Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Secret rotation completed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Secret rotation completed successfully" } } } } } ] } } } }, "400": { "description": "No active rotation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/webhooks/{webhookId}/reset-circuit-breaker": { "post": { "summary": "Reset circuit breaker", "description": "Reset the circuit breaker for a webhook subscription.\n\n**Requires:** Workspace access\n\n**Circuit Breaker States:**\n- **CLOSED:** Normal operation\n- **OPEN:** Delivery paused (too many failures)\n- **HALF_OPEN:** Testing recovery\n\nUse this to manually reset after fixing endpoint issues.\n", "operationId": "resetWorkspaceWebhookCircuitBreaker", "tags": [ "Workspace Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Circuit breaker reset successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "circuitBreakerState": { "type": "string", "enum": [ "CLOSED", "OPEN", "HALF_OPEN" ], "example": "CLOSED" }, "message": { "type": "string", "example": "Circuit breaker reset to CLOSED" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/webhooks/{webhookId}/test": { "post": { "summary": "Test webhook endpoint", "description": "Send a test event to the webhook endpoint.\n\n**Requires:** Workspace access\n\nUseful for verifying your endpoint is correctly configured\nand can receive events.\n", "operationId": "testWorkspaceWebhook", "tags": [ "Workspace Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Test event sent", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the test delivery succeeded", "example": true }, "statusCode": { "type": "integer", "description": "HTTP status code from the endpoint", "example": 200 }, "responseTime": { "type": "integer", "description": "Response time in milliseconds", "example": 150 }, "error": { "type": "string", "description": "Error message if failed", "nullable": true } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/webhooks/events/types": { "get": { "summary": "List webhook event types", "description": "Get all available webhook event types that can be subscribed to.\n\n**Requires:** Workspace access\n", "operationId": "listWorkspaceWebhookEventTypes", "tags": [ "Workspace Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event types retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "eventTypes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "transaction.created" }, "description": { "type": "string", "example": "Triggered when a new transaction is created" }, "category": { "type": "string", "example": "transactions" } } } } } } } } ] }, "example": { "success": true, "data": { "eventTypes": [ { "type": "transaction.created", "description": "A new transaction was created", "category": "transactions" }, { "type": "transaction.completed", "description": "A transaction was completed", "category": "transactions" }, { "type": "dispute.created", "description": "A dispute was opened", "category": "disputes" } ] }, "meta": { "timestamp": "2026-02-26T12:00:00Z", "requestId": "req_abc123" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/oauth/clients": { "get": { "summary": "List OAuth clients", "description": "Get all OAuth clients for a workspace.\n\n**Requires:** Workspace access\n", "operationId": "listWorkspaceOAuthClients", "tags": [ "Workspace OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OAuth clients retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "clients": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthClient" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create OAuth client", "description": "Create a new OAuth client for a workspace.\n\n**Requires:** Workspace access\n\n**Note:** The client secret is only returned once at creation time.\n", "operationId": "createWorkspaceOAuthClient", "tags": [ "Workspace OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOAuthClientRequest" }, "example": { "name": "My API Client", "description": "Client for mobile app", "scopes": [ "transactions:read", "customers:write" ], "grantTypes": [ "client_credentials" ] } } } }, "responses": { "201": { "description": "OAuth client created successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OAuthClient" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/oauth/clients/{clientId}": { "get": { "summary": "Get OAuth client", "description": "Get details of a specific OAuth client.\n\n**Requires:** Workspace access\n", "operationId": "getWorkspaceOAuthClient", "tags": [ "Workspace OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "description": "OAuth client ID (e.g., coinbax_client_xxx)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth client retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OAuthClient" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "summary": "Update OAuth client", "description": "Update an OAuth client's settings.\n\n**Requires:** Workspace access\n\n**Note:** Deactivating a client will revoke all its tokens.\n", "operationId": "updateWorkspaceOAuthClient", "tags": [ "Workspace OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "description": "OAuth client ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOAuthClientRequest" }, "example": { "name": "Updated Client Name", "description": "Updated description", "scopes": [ "transactions:read", "customers:read" ], "isActive": true } } } }, "responses": { "200": { "description": "OAuth client updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OAuthClient" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete OAuth client", "description": "Permanently delete an OAuth client.\n\n**Requires:** Workspace access\n\n**Warning:** This action is irreversible and will revoke all associated tokens.\n", "operationId": "deleteWorkspaceOAuthClient", "tags": [ "Workspace OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "description": "OAuth client ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "OAuth client deleted successfully (no content)" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/oauth/clients/{clientId}/revoke-tokens": { "post": { "summary": "Revoke OAuth client tokens", "description": "Revoke all active access tokens for an OAuth client.\n\n**Requires:** Workspace access\n\nUse this when you need to immediately invalidate all tokens without\ndeleting the client itself.\n", "operationId": "revokeWorkspaceOAuthClientTokens", "tags": [ "Workspace OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "description": "OAuth client ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tokens revoked successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "count": { "type": "integer", "description": "Number of tokens revoked", "example": 5 } } } } } ] }, "example": { "success": true, "data": { "count": 5 }, "meta": { "timestamp": "2026-02-26T12:00:00Z", "requestId": "req_abc123" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/oauth/clients/{clientId}/stats": { "get": { "summary": "Get OAuth client statistics", "description": "Get token usage statistics for an OAuth client.\n\n**Requires:** Workspace access\n", "operationId": "getWorkspaceOAuthClientStats", "tags": [ "Workspace OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "description": "OAuth client ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Statistics retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalTokens": { "type": "integer", "description": "Total tokens ever issued", "example": 150 }, "activeTokens": { "type": "integer", "description": "Currently active tokens", "example": 12 }, "revokedTokens": { "type": "integer", "description": "Revoked tokens", "example": 138 } } } } } ] }, "example": { "success": true, "data": { "totalTokens": 150, "activeTokens": 12, "revokedTokens": 138 }, "meta": { "timestamp": "2026-02-26T12:00:00Z", "requestId": "req_abc123" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/oauth/scopes": { "get": { "summary": "List available OAuth scopes", "description": "Get all available OAuth scopes that can be assigned to clients.\n\n**Requires:** Workspace access\n\nScopes control what actions an OAuth client can perform.\n", "operationId": "listWorkspaceOAuthScopes", "tags": [ "Workspace OAuth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scopes retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthScope" } } } } } } ] }, "example": { "success": true, "data": { "scopes": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "scope": "transactions:read", "resource": "transactions", "action": "read", "description": "Read transaction data", "isActive": true }, { "id": "550e8400-e29b-41d4-a716-446655440001", "scope": "transactions:write", "resource": "transactions", "action": "write", "description": "Create and update transactions", "isActive": true } ] }, "meta": { "timestamp": "2026-02-26T12:00:00Z", "requestId": "req_abc123" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/integrations": { "get": { "summary": "List workspace integrations", "description": "Get all integrations enabled for a workspace.\n\n**Requires:** Workspace access\n", "operationId": "listWorkspaceIntegrations", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Integrations retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceIntegration" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Enable integration", "description": "Enable an integration for a workspace.\n\n**Requires:** Workspace access\n", "operationId": "enableWorkspaceIntegration", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableIntegrationRequest" }, "example": { "integrationId": "550e8400-e29b-41d4-a716-446655440000", "config": { "apiKey": "integration_api_key" } } } } }, "responses": { "200": { "description": "Integration enabled successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkspaceIntegration" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/contracts": { "get": { "summary": "List contract deployments", "description": "Get all contract deployments for a workspace.\nReturns both dedicated and shared contract deployments.\n\n**Requires:** Workspace access\n", "operationId": "listWorkspaceContracts", "tags": [ "Smart Contracts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Contract deployments retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContractDeployment" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/contracts/{network}": { "get": { "summary": "Get escrow contract address for network", "description": "Get the escrow contract address for a workspace on a specific network.\nReturns a dedicated contract if one exists, otherwise falls back to shared.\n\n**Requires:** Workspace access\n", "operationId": "getWorkspaceContractByNetwork", "tags": [ "Smart Contracts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "network", "in": "path", "required": true, "description": "Blockchain network", "schema": { "type": "string", "enum": [ "base-sepolia", "base", "ethereum-sepolia", "ethereum" ] } } ], "responses": { "200": { "description": "Contract address retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "address": { "type": "string", "description": "Contract address" }, "network": { "type": "string" }, "isShared": { "type": "boolean" }, "deploymentId": { "type": "string", "format": "uuid" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No escrow contract deployed for network", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Deploy dedicated escrow contract", "description": "Deploy a dedicated escrow contract for a workspace on a specific network.\nThis will create a new WorkspaceEscrow contract via the factory.\n\n**Permissions:** Admin only\n", "operationId": "deployWorkspaceContract", "tags": [ "Smart Contracts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "network", "in": "path", "required": true, "description": "Blockchain network", "schema": { "type": "string", "enum": [ "base-sepolia", "base", "ethereum-sepolia", "ethereum" ] } } ], "responses": { "201": { "description": "Contract deployed successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deploymentId": { "type": "string", "format": "uuid" }, "contractAddress": { "type": "string" }, "transactionHash": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "DEPLOYED", "FAILED" ] }, "network": { "type": "string" }, "gasUsed": { "type": "string" }, "blockNumber": { "type": "integer" } } } } } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Workspace already has a dedicated contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "Deployment not available for network", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspaces/{id}/contracts/deployments/{deploymentId}/deprecate": { "post": { "summary": "Deprecate contract deployment", "description": "Mark a contract deployment as deprecated.\nDeprecated contracts will no longer be used for new transactions.\n\n**Permissions:** Admin only\n", "operationId": "deprecateContractDeployment", "tags": [ "Smart Contracts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "deploymentId", "in": "path", "required": true, "description": "Contract deployment ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Contract deprecated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContractDeployment" } } } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/external-wallet-configs": { "get": { "summary": "List external wallet configs", "description": "Get all external wallet provider configurations for a workspace.\nThese configs determine which wallet providers (MetaMask, WalletConnect, etc.)\ncustomers can use.\n\n**Requires:** Workspace access\n", "operationId": "listExternalWalletConfigs", "tags": [ "Wallet Configs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "External wallet configs retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "configs": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalWalletConfig" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/external-wallet-configs/{type}": { "get": { "summary": "Get external wallet config", "description": "Get a specific external wallet config by provider type.\n\n**Requires:** Workspace access\n", "operationId": "getExternalWalletConfig", "tags": [ "Wallet Configs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "path", "required": true, "description": "External wallet provider type", "schema": { "type": "string", "enum": [ "METAMASK", "WALLET_CONNECT", "COINBASE_WALLET", "LEDGER" ] } } ], "responses": { "200": { "description": "External wallet config retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalWalletConfig" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "summary": "Create or update external wallet config", "description": "Create or update an external wallet provider configuration.\n\n**Requires:** Workspace access\n", "operationId": "updateExternalWalletConfig", "tags": [ "Wallet Configs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "path", "required": true, "description": "External wallet provider type", "schema": { "type": "string", "enum": [ "METAMASK", "WALLET_CONNECT", "COINBASE_WALLET", "LEDGER" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExternalWalletConfigRequest" }, "example": { "isEnabled": true, "allowedNetworks": [ "BASE_SEPOLIA", "ETHEREUM_SEPOLIA" ], "config": { "projectId": "your_wallet_connect_project_id" } } } } }, "responses": { "200": { "description": "External wallet config updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalWalletConfig" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete external wallet config", "description": "Delete an external wallet provider configuration.\n\n**Requires:** Workspace access\n", "operationId": "deleteExternalWalletConfig", "tags": [ "Wallet Configs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "path", "required": true, "description": "External wallet provider type", "schema": { "type": "string", "enum": [ "METAMASK", "WALLET_CONNECT", "COINBASE_WALLET", "LEDGER" ] } } ], "responses": { "200": { "description": "External wallet config deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Config deleted successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/customers/auth/register": { "post": { "summary": "Register customer", "description": "Register a new customer for a workspace.\n\n**Authentication:** Public endpoint (no auth required)\n", "operationId": "registerWorkspaceCustomer", "tags": [ "Workspace Customers" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID or slug", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRegisterRequest" }, "example": { "email": "customer@example.com", "password": "securePassword123", "firstName": "John", "lastName": "Doe" } } } }, "responses": { "201": { "description": "Customer registered successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerAuthResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/customers/auth/login": { "post": { "summary": "Login customer", "description": "Authenticate a customer and receive access tokens.\n\n**Authentication:** Public endpoint (no auth required)\n", "operationId": "loginWorkspaceCustomer", "tags": [ "Workspace Customers" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID or slug", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoginRequest" }, "example": { "email": "customer@example.com", "password": "securePassword123" } } } }, "responses": { "200": { "description": "Customer logged in successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerAuthResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/customers/auth/me": { "get": { "summary": "Get current customer", "description": "Get the current authenticated customer's profile.\n\n**Requires:** Customer authentication (workspace-specific JWT)\n", "operationId": "getCurrentWorkspaceCustomer", "tags": [ "Workspace Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID or slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer profile retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerProfile" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/customers/auth/refresh": { "post": { "summary": "Refresh customer token", "description": "Refresh an expired access token using a refresh token.\n\n**Authentication:** Public endpoint (no auth required)\n", "operationId": "refreshWorkspaceCustomerToken", "tags": [ "Workspace Customers" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID or slug", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRefreshTokenRequest" } } } }, "responses": { "200": { "description": "Token refreshed successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerAuthResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/customers/auth/link-wallet": { "post": { "summary": "Link wallet to customer", "description": "Link an external wallet address to the customer account.\nRequires signature verification to prove wallet ownership.\n\n**Requires:** Customer authentication (workspace-specific JWT)\n", "operationId": "linkWorkspaceCustomerWallet", "tags": [ "Workspace Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID or slug", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLinkWalletRequest" }, "example": { "walletAddress": "0x1234567890abcdef1234567890abcdef12345678", "signature": "0x...", "message": "Link wallet to Coinbax: 1234567890" } } } }, "responses": { "200": { "description": "Wallet linked successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerProfile" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/customers/auth/wallet": { "get": { "summary": "Get customer wallet", "description": "Get the linked wallet address for the current customer.\n\n**Requires:** Customer authentication (workspace-specific JWT)\n", "operationId": "getWorkspaceCustomerWallet", "tags": [ "Workspace Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID or slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Wallet information retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "walletAddress": { "type": "string", "nullable": true }, "walletLinkedAt": { "type": "string", "format": "date-time", "nullable": true } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/workspaces/{id}/audit-logs": { "get": { "summary": "List workspace audit logs", "description": "Get audit logs for a workspace.\n\n**Permissions:** ADMIN or SUPER_ADMIN only\n", "operationId": "listWorkspaceAuditLogs", "tags": [ "Audit Logs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Audit logs retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } }, "meta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/health/database": { "get": { "summary": "Database health check", "operationId": "healthCheckDatabase", "tags": [ "Health" ], "responses": { "200": { "description": "Database is healthy" }, "503": { "description": "Database is unhealthy" } } } }, "/health/redis": { "get": { "summary": "Redis health check", "operationId": "healthCheckRedis", "tags": [ "Health" ], "responses": { "200": { "description": "Redis is healthy" }, "503": { "description": "Redis is unhealthy" } } } }, "/health/storage": { "get": { "summary": "Storage health check", "operationId": "healthCheckStorage", "tags": [ "Health" ], "responses": { "200": { "description": "Storage is healthy" }, "503": { "description": "Storage is unhealthy" } } } }, "/auth/change-password": { "post": { "summary": "Change password", "operationId": "authChangePassword", "tags": [ "Authentication" ], "responses": { "200": { "description": "Password changed" } } } }, "/auth/request-password-reset": { "post": { "summary": "Request password reset", "operationId": "authRequestPasswordReset", "tags": [ "Authentication" ], "responses": { "200": { "description": "Reset email sent" } } } }, "/auth/reset-password": { "post": { "summary": "Reset password", "operationId": "authResetPassword", "tags": [ "Authentication" ], "responses": { "200": { "description": "Password reset" } } } }, "/auth/verify-email": { "post": { "summary": "Verify email address", "operationId": "authVerifyEmail", "tags": [ "Authentication" ], "responses": { "200": { "description": "Email verified" } } } }, "/auth/link-oauth": { "post": { "summary": "Link OAuth provider", "operationId": "authLinkOAuth", "tags": [ "Authentication" ], "responses": { "200": { "description": "Provider linked" } } } }, "/auth/unlink-oauth": { "post": { "summary": "Unlink OAuth provider", "operationId": "authUnlinkOAuth", "tags": [ "Authentication" ], "responses": { "200": { "description": "Provider unlinked" } } } }, "/auth/linked-accounts": { "get": { "summary": "List linked OAuth accounts", "operationId": "authListLinkedAccounts", "tags": [ "Authentication" ], "responses": { "200": { "description": "Accounts retrieved" } } } }, "/auth/google/exchange-code": { "post": { "summary": "Exchange Google OAuth code", "operationId": "authGoogleExchangeCode", "tags": [ "Authentication" ], "responses": { "200": { "description": "Authentication successful" } } } }, "/auth/microsoft/exchange-code": { "post": { "summary": "Exchange Microsoft OAuth code", "operationId": "authMicrosoftExchangeCode", "tags": [ "Authentication" ], "responses": { "200": { "description": "Authentication successful" } } } }, "/audit-logs": { "get": { "summary": "List all audit logs", "operationId": "listAllAuditLogs", "tags": [ "Audit Logs" ], "responses": { "200": { "description": "Audit logs retrieved" } } } }, "/audit-logs/{id}": { "get": { "summary": "Get audit log entry", "operationId": "getAuditLog", "tags": [ "Audit Logs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Log retrieved" } } } }, "/audit-logs/export": { "get": { "summary": "Export audit logs", "operationId": "exportAuditLogs", "tags": [ "Audit Logs" ], "responses": { "200": { "description": "Export file" } } } }, "/audit-logs/stats": { "get": { "summary": "Get audit log statistics", "operationId": "getAuditLogStats", "tags": [ "Audit Logs" ], "responses": { "200": { "description": "Statistics retrieved" } } } }, "/workspaces/{id}/integrations/{integrationId}": { "get": { "summary": "Get integration details", "operationId": "getWorkspaceIntegration", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Integration retrieved" } } }, "patch": { "summary": "Update integration", "operationId": "updateWorkspaceIntegration", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Updated" } } }, "delete": { "summary": "Remove integration", "operationId": "deleteWorkspaceIntegration", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Removed" } } } }, "/workspaces/{id}/integrations/{integrationId}/disable": { "post": { "summary": "Disable integration", "operationId": "disableWorkspaceIntegration", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Disabled" } } } }, "/workspaces/{id}/integrations/{integrationId}/status": { "get": { "summary": "Get integration status", "operationId": "getWorkspaceIntegrationStatus", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Status retrieved" } } } }, "/workspaces/{id}/integrations/validate": { "post": { "summary": "Validate integration config", "operationId": "validateWorkspaceIntegration", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Validated" } } } }, "/workspaces/{id}/integrations/with-config": { "post": { "summary": "Enable integration with config", "operationId": "enableWorkspaceIntegrationWithConfig", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Enabled" } } } }, "/workspaces/{id}/avatar": { "post": { "summary": "Upload workspace avatar", "operationId": "uploadWorkspaceAvatar", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Uploaded" } } }, "delete": { "summary": "Delete workspace avatar", "operationId": "deleteWorkspaceAvatar", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/workspaces/{id}/billing": { "get": { "summary": "Get workspace billing", "operationId": "getWorkspaceBilling", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Retrieved" } } } }, "/workspaces/{id}/platform-mappings": { "get": { "summary": "List platform mappings", "operationId": "listWorkspacePlatformMappings", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Retrieved" } } }, "post": { "summary": "Create platform mapping", "operationId": "createWorkspacePlatformMapping", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Created" } } } }, "/workspaces/{id}/platform-mappings/{mappingId}": { "delete": { "summary": "Delete platform mapping", "operationId": "deleteWorkspacePlatformMapping", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/workspaces/{id}/wallet-settings": { "get": { "summary": "Get wallet settings", "operationId": "getWorkspaceWalletSettings", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Retrieved" } } }, "patch": { "summary": "Update wallet settings", "operationId": "updateWorkspaceWalletSettings", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Updated" } } } }, "/workspaces/search": { "get": { "summary": "Search workspaces", "operationId": "searchWorkspaces", "tags": [ "Workspaces" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Results" } } } }, "/onboarding": { "get": { "summary": "Get onboarding status", "operationId": "getOnboardingStatus", "tags": [ "Onboarding" ], "responses": { "200": { "description": "Status" } } } }, "/onboarding/complete": { "post": { "summary": "Complete onboarding", "operationId": "completeOnboarding", "tags": [ "Onboarding" ], "responses": { "200": { "description": "Completed" } } } }, "/onboarding/skip": { "post": { "summary": "Skip onboarding", "operationId": "skipOnboarding", "tags": [ "Onboarding" ], "responses": { "200": { "description": "Skipped" } } } }, "/onboarding/create-client": { "post": { "summary": "Create client", "operationId": "onboardingCreateClient", "tags": [ "Onboarding" ], "responses": { "201": { "description": "Created" } } } }, "/users/me/avatar": { "post": { "summary": "Upload user avatar", "operationId": "uploadUserAvatar", "tags": [ "Users" ], "responses": { "200": { "description": "Uploaded" } } }, "delete": { "summary": "Delete user avatar", "operationId": "deleteUserAvatar", "tags": [ "Users" ], "responses": { "204": { "description": "Deleted" } } } }, "/users/me/password": { "patch": { "summary": "Update password", "operationId": "updateUserPassword", "tags": [ "Users" ], "responses": { "200": { "description": "Updated" } } } }, "/users/{id}/audit-logs": { "get": { "summary": "Get user audit logs", "operationId": "getUserAuditLogs", "tags": [ "Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Retrieved" } } } }, "/settings/{key}": { "get": { "summary": "Get setting", "operationId": "getSettingByKey", "tags": [ "Settings" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved" } } }, "put": { "summary": "Update setting", "operationId": "updateSetting", "tags": [ "Settings" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated" } } } }, "/global-settings": { "get": { "summary": "List global settings", "operationId": "listGlobalSettings", "tags": [ "Settings" ], "responses": { "200": { "description": "Retrieved" } } } }, "/global-settings/bulk": { "post": { "summary": "Update settings bulk", "operationId": "updateGlobalSettingsBulk", "tags": [ "Settings" ], "responses": { "200": { "description": "Updated" } } } }, "/notifications/{id}": { "get": { "summary": "Get notification", "operationId": "getNotification", "tags": [ "Notifications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Retrieved" } } } }, "/notifications/preferences": { "get": { "summary": "Get preferences", "operationId": "getNotificationPreferences", "tags": [ "Notifications" ], "responses": { "200": { "description": "Retrieved" } } }, "patch": { "summary": "Update preferences", "operationId": "updateNotificationPreferences", "tags": [ "Notifications" ], "responses": { "200": { "description": "Updated" } } } } } }