Portal Integrations

The One Portal integrates with several products in The One Stack to pull and push data on behalf of portal clients.

---

The One PSA

Direction: Bidirectional Data flows: Tickets, client users, company records

What	How
Tickets created in Portal	Synced to PSA via the ticket-sync background timer (every 5 minutes)
Ticket status/comment updates in PSA	Reflected in Portal on the next sync cycle
PSA contact "portal access" enabled	Auto-provisions a ClientUser in Portal
Hub SSO login link	Generated by PSA when a contact accesses the portal from a PSA link

Required env vars:

• PSA_API_URL — PSA API base URL
• PSA_SERVICE_KEY — service-to-service integration key for PSA → Portal

Setup:

1. In The One PSA, go to Settings → Integrations → Portal
2. Enable the Portal integration and copy the integration key
3. Set the key as PSA_SERVICE_KEY on the Portal API Function App

What breaks if misconfigured:

• Tickets created in Portal will not appear in PSA (technicians won't see them)
• Hub SSO login for client users will fail
• Contact portal-access provisioning will not work

---

The One Hub

Direction: Outbound (Hub → Portal) Data flows: SSO login, Hub Bar product switcher

What	How
Hub SSO login	Hub generates a signed JWT; Portal validates at /api/auth/client-hub-sso
Hub Bar	Embedded in every Portal page via @theonefamily/hub-bar package

Required env vars:

• PORTAL_CLIENT_SSO_SECRET — shared secret between Hub and Portal for JWT signing
• VITE_HUB_URL — Hub frontend URL (for Hub Bar links)
• VITE_BUS_URL — Event Bus API URL (for Hub Bar cross-product notifications)

Setup:

1. Set PORTAL_CLIENT_SSO_SECRET to a strong random secret on both the Hub API and Portal API
2. In Hub Settings, configure the Portal redirect URL

---

The One Legal

Direction: Legal → Portal Data flows: Policy documents pushed for client signature

What	How
Policy published to clients	Legal API calls Portal's /internal/signing/push endpoint
Client signs in Portal	Acknowledgement record created; Legal API notified via webhook

Required env vars on Legal API:

• PORTAL_API_URL — Portal API base URL
• PORTAL_INTEGRATION_KEY — Integration key for Legal → Portal calls

Required env vars on Portal API:

• LEGAL_WEBHOOK_URL — Where to send signature completion events

What breaks if misconfigured:

• Policies created in Legal will not appear in the Portal for client signature
• Signed acknowledgements will not sync back to Legal

---

The One Mission

Direction: Mission → Portal (via proxy) Data flows: Donations, events, groups, members, prayer requests

What	How
Giving history	Proxied from /mission/donations and /mission/donations/stats
Events	Proxied from /mission/events
Groups	Proxied from /mission/groups
Member directory	Proxied from /mission/directory
Prayer requests	Proxied from /mission/prayer; POST to submit a new request

All Mission data flows through the mission-proxy Azure Function in the Portal API. This function forwards authenticated requests to The One Mission API and returns the response.

Required env vars:

• MISSION_API_URL — The One Mission API base URL
• MISSION_SERVICE_KEY — Service key for Portal → Mission API calls

What breaks if misconfigured:

• All Mission portal pages (Giving, Events, Groups, Directory, Prayer) return empty or error
• Mission members see no data in their portal

---

The One Books

Direction: Books → Portal Data flows: Invoice records

What	How
Invoices	Synced from Books via the invoice-sync background timer (every 6 hours)

Required env vars:

• BOOKS_API_URL — Books API base URL
• BOOKS_SERVICE_KEY — Integration key for Books → Portal sync

What breaks if misconfigured:

• Invoice page shows no invoices for clients
• New invoices issued in Books do not appear in Portal

---

Azure Communication Services / AWS SES

Direction: Outbound (Portal → Email) Data flows: Password reset emails, invite emails, signing notification emails

The Portal sends transactional emails via AWS SES (or Azure Communication Services as fallback) for:

• New user invitation with password-set link
• Password reset links
• Document signing notifications (portal-signing-notify function)

Required env vars:

• SES_FROM_ADDRESS — Sender email address (must be SES-verified)
• SES_REGION — AWS region

---

Integration Health Check

If a portal feature is broken, use this checklist:

Feature	First thing to check
Tickets not syncing to PSA	PSA_SERVICE_KEY set? PSA integration enabled?
Hub SSO login failing	PORTAL_CLIENT_SSO_SECRET matches on both Hub and Portal?
Documents not showing for signature	PORTAL_INTEGRATION_KEY set on Legal API?
Mission pages empty	MISSION_API_URL and MISSION_SERVICE_KEY set? Mission API up?
Invoices not appearing	BOOKS_SERVICE_KEY set? 6-hour sync timer fired?
Invite emails not sending	SES_FROM_ADDRESS verified in AWS SES?

ℹ️

All integration keys should be stored in Azure Key Vault and referenced as Key Vault references in the Function App application settings — never stored as plaintext environment variables.