EHQ Brain

ADR-014 White-Label & BYOAK

2 min read

ADR-014: White-Label Strategy & Bring Your Own API Keys (BYOAK)

Status: Proposed Owner: @bilal @deen Date: 2026-02-10

Context

As Envo scales, larger property management companies will expect customisation — from basic branding to fully white-labelled instances. This ADR addresses:

  1. BYOAK — Allowing premium organisations to use their own Twilio, SendGrid, LLM, and other service accounts
  2. White-Label Tiers — Spectrum of customisation available at each plan level

Current State

  • All integrations use shared Envo credentials via env vars
  • No per-org branding, theming, or styling
  • organisations.plan enum exists but isn’t used for feature gating
  • Provider abstractions exist (LLM registry, tenant intake adapters)
  • Multi-tenant RLS isolation is solid (ADR-001 Multi-Tenancy Access Model)

Decision

Three-Tier White-Label Model

CapabilityBasicPremiumPartner
Custom logo + colour palette—YesYes
Custom email templates—YesYes
Own SendGrid / LLM API keys—YesYes
Custom domain (dashboard + tenant)——Yes
Own Twilio / VAPI account——Yes
Remove “Powered by Envo”——Yes
SSO / SAML——Yes

BYOAK Architecture

Credential resolution order: Org-specific credentials (from integration_credentials) → Envo platform defaults (env vars).

Key tables:

  • integration_credentials — Per-org encrypted credentials (via Supabase Vault/pgsodium), with verification status
  • integration_settings — Provider selection per org (SMS, WhatsApp, email, voice, LLM)
  • organisation_branding — Logo, colours, custom domain, email/SMS branding, “powered by” toggle

Security: All API keys stored via Supabase Vault. Application code never handles raw encryption. 5-minute in-memory cache, invalidated via Supabase Realtime.

Webhook Routing

BYOAK orgs: query parameter routing (/api/webhooks/whatsapp?org={id}) with per-org webhook secret validation. Shared account orgs: phone number lookup.

White-Label Theming

CSS custom properties injected at layout level — maps directly to ShadCN/ui theme variables.

Custom Domain Routing (Partner tier)

DNS verification flow → TLS provisioning via Vercel/Cloudflare → Middleware resolves Host header to organisation.

Implementation Phases

  1. Foundation (Weeks 1-3): DB migration, Vault integration, credential resolver
  2. Easy BYOAK (Weeks 4-6): SendGrid + LLM key swap, settings UI
  3. Branding (Weeks 5-7): Theming pipeline, logo upload, email branding
  4. Twilio/Voice BYOAK (Weeks 7-9): Webhook routing, SMS sender ID
  5. Partner Tier (Weeks 9-12): Custom domains, SSO/SAML

Consequences

Positive

  • Revenue differentiation with clear upgrade path
  • Reduced platform cost at scale (orgs pay own API bills)
  • Enterprise readiness (white-labelling is table stakes)
  • High stickiness once configured

Negative

  • Support complexity increases (debugging customer’s own API keys)
  • Onboarding friction (BYOAK setup requires third-party accounts)
  • Credential security responsibility (Envo stores customer keys)

Graph View

Backlinks