virtual-banker/docs/API.md

Virtual Banker API Reference

Base URL

http://localhost:8081

Authentication

All requests (except health check) require authentication via JWT token in the Authorization header:

Authorization: Bearer <jwt-token>

Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy"
}

Create Session

POST /v1/sessions

Request Body:

{
  "tenant_id": "tenant-123",
  "user_id": "user-456",
  "auth_assertion": "jwt-token",
  "portal_context": {
    "route": "/account",
    "account_id": "acc-789"
  }
}

Response:

{
  "session_id": "sess-abc123",
  "ephemeral_token": "ephemeral-token-xyz",
  "config": {
    "theme": {
      "primaryColor": "#0066cc"
    },
    "avatar_enabled": true,
    "greeting": "Hello! How can I help you today?",
    "allowed_tools": ["get_account_status", "create_ticket"],
    "policy": {
      "max_session_duration_minutes": 30,
      "rate_limit_per_minute": 10,
      "require_consent": true
    }
  },
  "expires_at": "2024-01-20T15:30:00Z"
}

Refresh Token

POST /v1/sessions/{session_id}/refresh-token

Response:

{
  "ephemeral_token": "new-ephemeral-token",
  "expires_at": "2024-01-20T15:35:00Z"
}

End Session

POST /v1/sessions/{session_id}/end

Response:

{
  "status": "ended"
}

Error Responses

All errors follow this format:

{
  "error": "Error message",
  "message": "Detailed error description"
}

Status Codes

• 200 OK - Success
• 201 Created - Resource created
• 400 Bad Request - Invalid request
• 401 Unauthorized - Authentication required
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

WebRTC Signaling

WebRTC signaling is handled via WebSocket (to be implemented in Phase 1):

WS /v1/realtime/{session_id}

Rate Limiting

Rate limits are enforced per tenant and user:

• Default: 10 requests per minute per user
• Configurable per tenant

Rate limit headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1642680000