​

Deploying secure internal apps

​

1. What “built on the substrate” means

• No bespoke data layer per app. Your portal and your Slack agent agree on what “a job at Berwyn House” is, because both read the same model.
• Thin apps are appropriate. Internal apps focus on workflow and UX; the substrate handles enrichment, resolution, and synthesis.
• Switching surfaces is cheap. Replacing a UI does not invalidate the operational picture.

​

2. Access patterns (choose one)

​

3. Security model (IT checklist)

​

Data scoping and user management

• All API calls are scoped by company_id. Tenant resolution happens server-side, no API call can cross organisation boundaries.
• The platform ships with built-in user management: invite users, assign roles, organise teams, and issue JWTs without building any of that yourself. See Users and teams.
• Dedicated, isolated infrastructure is available on Enterprise plans.

​

JWTs and sessions

• Login returns a JWT valid for 24 hours. Refresh issues a new 24-hour token.
• Plan a refresh policy: silent refresh during active sessions; re-login at idle thresholds your security team is comfortable with.
• Do not store the JWT in non-HTTP-only storage if you can avoid it. Treat it as a session credential.

​

Internal IDs and PII

• Internal IDs (company_id, job_id, contact_id, resource_id) belong on the server.
• UI should show names and job references, not internal IDs (Connie follows the same rule, see Connie).
• PII in UI is a product policy decision. Decide once, enforce in the app layer.

​

BYOK (Connie and agents)

• Conversational AI runs on your model provider key.
• Cost lands on your provider account at your contracted rate. No vendor margin.
• See Pricing and Connie for the BYOK model.

​

Timeouts

• Discovery completes sub-second. Set tight client timeouts.
• Connie and /investigate are multi-step. Plan for 20 to 25 seconds, longer on cold caches.
• Apps should surface a loading state for synthesis; do not pretend it is instant.

​

4. Building a custom app: the right architecture

​

The required split

• Frontend (what runs in the browser): handles display, navigation, and user interaction. Contains no credentials. Makes API calls only to your own backend.
• Backend (a server you control): holds credentials, validates identity, and makes all calls to the VH3 API. The browser never calls VH3 directly.

Browser
  │  calls your backend only (no VH3 credentials)
  ▼
Your backend server
  │  validates JWT → calls GET /auth/me → gets company_id
  │  makes VH3 API call with api_key from environment variable
  ▼
VH3 API  (api.vh3connect.io)

​

Authentication flow for a custom app

1. User visits your app and is redirected to your login page.
2. Your login page posts email and password to your backend (not directly to VH3).
3. Your backend calls POST https://api.vh3connect.io/api:lBQnyyZL/auth/login and receives the authToken.
4. Your backend sets the authToken as an httpOnly secure cookie on the response. The browser stores it automatically and sends it on every subsequent request. The token itself is never accessible to JavaScript.
5. On every protected request from the browser, your backend reads the cookie, calls GET https://api.vh3connect.io/api:lBQnyyZL/auth/me with the token to validate it and retrieve the user’s company_id.
6. Your backend uses the verified company_id and the api_key from its environment variables to call the VH3 API. It returns only the data the frontend needs.

​

What this looks like in practice (Node.js / Express)

// Backend route — runs on your server, never in the browser
app.get('/api/jobs', async (req, res) => {
  const token = req.cookies.vh3_token;
  if (!token) return res.status(401).json({ error: 'Not authenticated' });

  // Validate the token and get the user's company
  const meResponse = await fetch('https://api.vh3connect.io/api:lBQnyyZL/auth/me', {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!meResponse.ok) return res.status(401).json({ error: 'Session expired' });

  const { company_id } = await meResponse.json();

  // Call VH3 with server-side credentials
  const jobsResponse = await fetch('https://api.vh3connect.io/api:kP8T1CK7/jobs/feed', {
    method: 'GET',
    headers: { 'Content-Type': 'application/json' },
    // company_id and api_key stay on the server
    // pass them as query params or body per the API spec
  });

  // Return only what the frontend needs — strip internal IDs
  const data = await jobsResponse.json();
  res.json(data);
});

​

Environment variables and deployment

VH3_COMPANY_ID=your-company-id
VH3_API_KEY=your-api-key

​

CORS

app.use(cors({
  origin: 'https://your-frontend-domain.railway.app', // your frontend origin only
  credentials: true, // required for httpOnly cookie support
}));

​

5. Typical internal apps

​

6. Users, teams, and cases as governance

• Users and roles (Users, User Auth) decide who can sign in and what they can do.
• Teams (Teams) decide what each user sees and owns.
• Cases are the audit surface: status, participants, linked jobs, activity timeline. On Connect tier, cases are first-class.

1. A sentinel detects a pattern continuously (near-zero AI cost at detection).
2. A case is opened against the team that owns the affected customer or region.
3. The team uses discovery for precedents and Connie for a brief.
4. Decisions, replies, and follow-ups are logged against the case.

​

7. Tier and capability map

​

8. Deployment checklist

• Auth choice is explicit (Connect / JWT custom / server api_key / MCP JWT).
• api_key never appears in client code, browser bundles, or mobile binaries.
• JWT refresh policy is implemented; idle and absolute session limits are agreed with security.
• CORS allowlist is restricted to your app origins.
• Client timeouts: short for discovery, 20 to 25 seconds for synthesis.
• Role mapping is configured for the surfaces the app exposes (Core+ if you need bespoke roles).
• Teams are created and linked to the customers, sites, or regions they own.
• Connie answers in commercial or safety contexts route through Agent observability for evidence standards.
• Generative UI components render structured tool outputs from scoped, authenticated API responses only.
• PII and internal ID policy enforced in the app layer; UI shows names and job refs only.
• BYOK key set per environment; cost dashboards monitored on your provider account.
• Case ownership defined for each sentinel that the app surfaces.

​

Related