Technical & Architecture

API Overview

AI Diligence Console

API Overview

Date: 2026-05-14 Service: Rōvn Passport API (FastAPI on ECS Fargate, us-east-2) Title from main.py:53: Rovn Passport API, Healthcare workforce trust, credentialing, and Rōvn facility workflow layer infrastructure (code-level Rōvn identifier preserved as-is in source; rendered investor-facing surfaces use the macron form Rōvn)

1. Surface area

80+ routers registered. Grouped by domain:

Worker / Auth

/nurses/*, legacy nurse model surface
/worker/*, /worker-profile/*, /worker-profile/admin/*, /worker-profile/public/*, worker profile v2
/auth/*, /worker-auth/*, worker auth (Cognito)
/authkit/*, AuthKit worker onboarding
/identity/*, Persona IAL2 verification

Verification / Source authority

/verifications/*, verification orchestration
/licenses/*, license registry (migration 008 state+number idx)
/documents/*, document upload + OCR
/immunizations/*, immunization records
/exclusions/*, OIG LEIE + SAM exclusion check
/dea-verification/*, DEA verification
/npdb/*, NPDB Continuous Query workflow
/source-receipts/*, source receipt archive (admin)
/clinician-screens/*, clinician background screens

Passport

/passports/*, Passport issuance + retrieval
/public-verify/*, public verification surface (worker /p/{slug})
/profile-score/*, worker readiness score

Decision / Trust

/decision/*, verification decision rollup
/audit/*, hash-chained audit log replay
/jwks/*, JWKS for token verification
/trust-explorer/*, trust evidence explorer

facility workflow layer (facility cockpit)

/facility/command/*, facility workflow layer command center
/facility/overview/*, facility workflow layer overview
/facility/demand-talent/*, demand + talent surfaces
/facility/facility-users/*, facility user mgmt (legacy)
/facility/integrations/*, integration retry workbench
/facility/pipeline/*, hiring pipeline
/facility/ai-workbench/*, AI workbench
/facility/clearance/*, clearance status
/facility/readiness/*, readiness match
/facility/credentialing-workbench/*, credentialing workbench
/facility/active-staff/*, active staff monitoring
/facility/agency/*, agency relationships
/facility/binders/*, credential binders
/facility/trust-officer/*, trust officer surfaces
/facility/workers/*, /facility/expirables/*, worker view + expirables
/facility/jobs/*, facility workflow layer job surface
/facility/network/*, network apply
/facility/billing/*, facility workflow layer billing
/facility/bulk/*, bulk operations
/facility/facility-admin/*, facility admin

Hospital / Facility auth

/hospital-auth/*, legacy hospital auth
/sso/*, /sso/admin/*, WorkOS SSO
/admin-auth/*, admin auth

Marketplace

/jobs/*, job postings
/applications/*, applications
/messages/*, messaging
/matching/*, readiness match orchestration
/shifts/*, per-diem shifts
/worker-network/*, worker network apply + referral

Compliance / Operations

/requirements/*, /readiness/*, requirement evidence
/compact-intelligence/*, compact license intelligence
/career-pathing/*, career pathing
/risk-scoring/*, AI risk scoring
/hris-partners/*, HRIS integration
/benchmarking/*, data benchmarking
/copilot/*, AI copilot
/outcomes/*, outcomes tracking
/payor-integration/*, payer enrollment
/coverage-readiness/*, coverage readiness
/reverification/*, recredentialing cadence
/recredentialing-export/*, recredentialing export
/oppe-fppe/*, OPPE / FPPE workflows
/privileging/*, privileging workflow
/monitoring-actions/*, monitoring action center
/adverse-action/*, /adverse-action/posting/*, adverse action workflow

Catalog

/workforce-catalog/*, /workforce-catalog/worker/*, 43-role taxonomy

Other

/health, ECS health
/monitoring/*, internal monitoring
/webhooks/*, third-party webhook receiver
/billing/*, /subscriptions/*, Stripe billing
/experience/*, /experience/nurse/{id}, /experience/hospital/{id} aggregator surfaces
/credentialing/*, credentialing workflow
/worker-ai/*, /facility-ai/*, AI surfaces
/platform-expansion/*, platform expansion service rails
/mcp/*, MCP server (Bearer token)

2. Auth model

Surface	Auth	Notes
Worker surface (`/worker/`, `/nurse/`, `/authkit/*`)	AWS Cognito JWT	AuthKit smooths magic-link + phone flows
Hospital surface (`/portal`, `/facility/`, `/hospital/`)	WorkOS SSO (OIDC/SAML)	Per-hospital connection; admin fallback via `admin_auth.py`
Admin surface (`/admin/`, `/source-receipts/admin/`)	`require_admin` dependency	Custom admin role check
MCP server (`/mcp/*`)	Bearer token	Tokens stored in AWS Secrets Manager (memory `project_rovn_mcp_server_live.md`)
Public surface (`/p/{slug}`, `/public-verify/*`)	None (token in URL where needed)	Worker-controlled visibility, consent-gated fields
Health (`/health`)	None	ECS-only

3. Rate limits

Current posture: application-level rate limit middleware not yet in app/main.py. Rate limiting handled at: - AWS CloudFront / WAF layer for public surfaces, PARTIAL (in scope for SOC 2 Type II evidence) - Per-endpoint logic for verification orchestration (e.g., NPDB query cadence) via reverify_scheduler.py - Per-customer limits on Verified API (TARGET, to ship before first paying API customer)

Target posture (post-Series A): - Token-bucket per API key - Per-source authority cadence enforcement - AWS WAF tuned rules in front of all public endpoints

4. Idempotency

Stripe billing endpoints (billing.py): idempotency-key honored where Stripe SDK provides
Webhook receivers (webhooks.py): event-id deduplication
Verification enqueue (verifications.py): idempotency target, PARTIAL today; design-partner SLA may require harder guarantees, scheduled for Q3 2026

5. Webhooks

Inbound

Stripe billing events → /webhooks/stripe
Persona inquiry events → /webhooks/persona
Checkr background events → /webhooks/checkr
Nursys e-Notify events → /webhooks/nursys

Outbound (TARGET)

Customer webhooks on verification status change, TARGET, scheduled Q3 2026
Customer webhooks on credential expiration, TARGET
Webhook signature scheme: HMAC-SHA256 with shared secret per customer

6. MCP Server

/mcp exposes one zero-PHI tool: lookup_rovn_passport.

Bearer token auth (mcp_server.py:137)
JSON-RPC framing (_ok, _err helpers at :163, :167)
Inbound + outbound tokens stored in AWS Secrets Manager
Task definition :108 confirmed live; smoke green per memory log

7. OpenAPI / Docs

Development: /docs and /redoc and /openapi.json all enabled
Production: explicitly disabled (docs_url=None, redoc_url=None, openapi_url=None when environment == "production") per main.py:56-58
Procurement-grade API doc PDF: To generate from OpenAPI spec for data-room PDF (counsel-tracked)

8. Versioning

Current API version exposed at / root (app/main.py:163-174) returns version: _settings.version
No /v1/* path prefix yet, single-version surface
Versioning strategy on breakthrough customers: header-based Rovn-API-Version: 2026-05-14 rolling-date contract pattern (TARGET, to ship before first paying API customer)

9. Pagination

List endpoints use ?limit= + ?offset= or ?cursor= per endpoint
Default limit 25; max limit 100
Cursor pattern adopted on high-volume endpoints (audit events, applications, workers)

End of API overview.

Ask the AI agent about this section, the raise, compliance posture, or any cross-document question. Grounded in Rōvn's deep context, with on-page source citations.

AI queries route through AWS Bedrock under BAA · Anthropic Claude (Haiku 4.5) under BAA · zero-data-retention posture · no PHI in prompts.