Developer Documentation

# Loan Certifier Portal Embed — Installation Guide

## Overview
Embed the Loan Certifier agent portal inside your platform. Agents see their loans
and opportunities in one full-screen view with a back button that returns to your app.

## Prerequisites
1. You need a Loan Certifier API key (contact support to get one).
2. Your server must be able to make HTTPS POST requests to https://app.loancertifier.com/functions/generateEmbedToken.
3. Your API key must be stored server-side — NEVER expose it in client-side code.

## Step 1: Get Your API Key
Contact Loan Certifier support to receive your platform API key. This key identifies
your integration and is used to generate embed tokens for your users.

## Step 2: Generate an Embed Token (Server-Side)
When one of your users needs to view their loans, call generateEmbedToken with their
email address. The token is tied to that specific user — dual verification.

curl -X POST https://app.loancertifier.com/functions/generateEmbedToken \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "agent_email": "user@example.com" }'

Response:
{
  "token": "a1b2c3d4...",
  "embed_url": "https://app.loancertifier.com/AgentPortalEmbed?token=a1b2c3d4...",
  "expires_in": 3600
}

## Step 3: Embed the Portal (Client-Side)
Place an iframe in your app using the embed_url from Step 2. Add return_url so the
back button returns to your app:

<iframe
  src="https://app.loancertifier.com/AgentPortalEmbed?token=TOKEN&return_url=https://yourapp.com/dashboard"
  width="100%"
  height="800"
  frameborder="0"
  style="border: none;"
></iframe>

## Step 4 (Optional): Deep-Link to a Specific Record
If you know a specific loan ID, open directly to it:

<iframe
  src="https://app.loancertifier.com/AgentPortalEmbed?token=TOKEN&view=loan&id=LOAN_ID&return_url=https://yourapp.com/dashboard"
  width="100%"
  height="800"
  frameborder="0"
  style="border: none;"
></iframe>

## Step 5 (Optional): Listen for Events
Add a postMessage listener to receive back button and activity events:

window.addEventListener('message', function(event) {
  if (event.origin !== 'https://app.loancertifier.com') return;
  var data = event.data;
  if (!data || data.source !== 'loan-certifier') return;
  switch (data.type) {
    case 'back_requested': window.history.back(); break;
    case 'loan_viewed': console.log('Viewed:', data.payload.loan_id); break;
    case 'note_added': console.log('Note on:', data.payload.loan_id); break;
  }
});

## Token Refresh
Tokens expire after 1 hour. Regenerate before expiry if the user's session is longer.
For long-term integrations, ask about persistent tokens.

## Security
- API keys are server-side only — never in client code.
- Always verify event.origin before processing postMessage events.
- Configure allowed_origins on your API key to restrict which domains can embed.