Unified BFF covering two integration patterns that Parloa AMP cannot handle natively.
All /epic/* and /banno/* routes require X-BFF-Key header.
GET /.well-known/jwks-v2.json ← public; Epic verifies JWT signatures here GET /epic/patient?firstname=&lastname=&dob= ← identity validation (auth gate) GET /epic/appointment?patientId= ← next upcoming appointment GET /epic/slots?date=&provider= ← available slots (live + demo fallback) POST /epic/book ← book a slot (write capability) GET /epic/balance?patientId= ← account balance (sandbox stub)
GET /banno/authorize?state= ← returns the JH authorize URL for this session GET /banno/callback?code=&state= ← PUBLIC; JH redirects here, exchange happens server-side GET /banno/session?state= ← has the caller finished authorizing? GET /banno/customer?customerId=&state= GET /banno/balance?customerId=&state= GET /banno/transactions?accountId=&state=
The state value is what correlates an async browser redirect back to a live voice
session. It is issued at /banno/authorize, validated at the callback (single use, 10-minute
window), and then keys the cached token. Without JH credentials configured, the data routes return
source: "sample" payloads.
| Capability | Parloa Today | BFF Solution |
|---|---|---|
| RS384 JWT signing (Epic — Trust Model B) | ❌ No crypto in chain steps | ✓ RS384 via jsonwebtoken |
| JWKS endpoint hosting (Epic) | ❌ No stable HTTPS endpoint per integration | ✓ /.well-known/jwks-v2.json |
| OAuth callback URI (JH Banno — Trust Model A) | ❌ No hosted redirect URI | ✓ /banno/callback |
| Code → token exchange holding client_secret | ❌ Secret would sit in agent config | ✓ Server-side only |
| Correlating an async callback to a live session | ❌ No session-callback mapping | ✓ state-keyed token cache |
| Key custody | ❌ No KMS binding for agents | ✓ Env var (K8s Secret / Key Vault) or file |
| Caller authentication on BFF | ✓ X-BFF-Key (AMP Secret env var) | ✓ |
auth.parloa.cloud/callback/{integration-id} managed redirect URI
auth.parloa.cloud/jwks/{integration-id} managed JWKS endpoint, key in KMS
{{parloa.auth.token("integration-id")}} session-scoped token binding
Parloa chain step config: Set X-BFF-Key: {{BFF_API_KEY}} in headers.
Store BFF_API_KEY in AMP Environments → + Variable → toggle Secret.
GET /health for service status