Iframe Integration

API v1 is being deprecated. Use v2 for new integrations. For existing integrations, see the migration guide and API Reference v1.

Embed the full Artemis platform, a project proposal, or the design editor in an <iframe>, with login or token-based authentication.

Use data.id from API v2 project creation as PROJECT_ID. Utility setup and design may still be running; follow the project readiness guidance before expecting a completed design or calculated proposal.

How embedding works

Artemis’s frame-ancestors Content-Security-Policy blocks origins that are not allow-listed. See Allow-listing your domain.

Domains

EnvironmentBase URL
Productionhttps://sales.artemis.solar
Sandboxhttps://sales-sandbox.artemis.solar

Allow-listing your domain

Artemis serves a Content-Security-Policy header of the form:

frame-ancestors 'self' https://your-site.com https://app.your-site.com

Send Artemis engineering your exact embedding origins (scheme + host, e.g. https://app.your-site.com) for sandbox and production. Only allow-listed origins can embed.

If your origin isn't allow-listed, the browser silently refuses to render the iframe and logs a CSP error in the console. An iframe that "loads blank" is almost always a missing frame-ancestors entry.

Integration modes

Full Website

Embed the entire platform. Users log in inside the iframe and interact with Artemis normally.

<iframe
  src="https://sales.artemis.solar"
  width="100%"
  height="600"
  frameborder="0"
  allow="clipboard-write"
  title="Artemis"
></iframe>

Proposal Mode

Embed a project's full proposal (design, equipment, adders/discounts, utility details, payments, credit application, and contract), without a login screen. Authenticate with an impersonation token passed as the authToken query parameter.

<iframe
  src="https://sales.artemis.solar/projects/PROJECT_ID/proposal?authToken=YOUR_TOKEN"
  width="100%"
  height="600"
  frameborder="0"
  allow="clipboard-write"
  title="Artemis Proposal"
></iframe>

Design Mode

Embed just the design editor, where users edit the design and equipment. The canonical design URL is /d/{project_id}.

<iframe
  src="https://sales.artemis.solar/d/PROJECT_ID?authToken=YOUR_TOKEN"
  width="100%"
  height="600"
  frameborder="0"
  allow="clipboard-write"
  title="Artemis Design Mode"
></iframe>

Design Mode accepts query parameters to hide UI and lock down actions; see Design Mode query parameters below.

Authentication flow

For Proposal and Design modes you pass an authToken. Artemis validates it, exchanges it for session cookies, and strips the token from the URL. Artemis honors authToken only inside an iframe or on the /impersonate popup, which shows the token's account before you click; a top-level link with ?authToken= does not sign in.

Obtain the token from the Impersonate endpoint; it expires after 1 hour, so refresh it for long sessions.

Safari support

Safari blocks third-party cookies in cross-site iframes. Use a one-time popup and click Enable Authentication in the popup before loading the iframe:

This example shows a button on Safari and loads the iframe directly elsewhere:

<div id="iframe-container"></div>
<script>
  const authToken = 'YOUR_AUTH_TOKEN_HERE'
  const ARTEMIS = 'https://sales.artemis.solar'
  const isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent)

  if (isSafari) {
    const button = document.createElement('button')
    button.id = 'load-iframe-btn'
    button.textContent = 'Load Design'
    button.onclick = enableIframeAuth
    document.body.insertBefore(button, document.getElementById('iframe-container'))
  } else {
    loadIframe(true)
  }

  function enableIframeAuth() {
    const button = document.getElementById('load-iframe-btn')
    button.disabled = true
    button.textContent = 'Loading...'

    const popup = window.open(
      `${ARTEMIS}/impersonate?authToken=${authToken}`,
      'auth-setup',
      'width=400,height=400,scrollbars=yes,resizable=yes'
    )

    window.addEventListener('message', function handler(event) {
      if (event.origin !== ARTEMIS) return
      if (event.data?.type === 'CLOSE_POPUP') {
        popup.close()
        window.removeEventListener('message', handler)
        loadIframe(false) // cookie is set, no authToken needed
      }
    })
  }

  function loadIframe(withToken) {
    const iframe = document.createElement('iframe')
    const base = `${ARTEMIS}/d/YOUR_PROJECT_ID`
    iframe.src = withToken ? `${base}?authToken=${authToken}` : base
    iframe.allow = 'clipboard-write'
    iframe.style.width = '100%'
    iframe.style.height = '800px'
    iframe.style.border = '0'
    document.getElementById('iframe-container').appendChild(iframe)
  }
</script>

The postMessage protocol

Listen for these window.postMessage events on the parent page:

Message (event.data.type)When it firesWhat you should do
AUTH_REQUIREDThe session token was rejected or expiredGenerate a fresh impersonation token and reload the iframe
projectUpdatedDesign Mode posts this on any proposal change (debounced); also carries the project id as event.data.projectIdRe-fetch the project to mirror the latest design and pricing
DESIGN_UPDATEDA design is saved in the editorRefresh your own UI / re-fetch the project if you mirror its data
CLOSE_POPUPThe Safari /impersonate popup finished setting cookiesClose the popup and render the iframe
// Whichever Artemis environment you embed (use only the one you embed)
const ARTEMIS_ORIGINS = [
  'https://sales.artemis.solar',
  'https://sales-sandbox.artemis.solar',
]

window.addEventListener('message', (event) => {
  // Always validate the sender's origin before trusting a message
  if (!ARTEMIS_ORIGINS.includes(event.origin)) return

  switch (event.data?.type) {
    case 'AUTH_REQUIRED':
      refreshTokenAndReloadIframe()
      break
    case 'projectUpdated':
      refetchProject(event.data.projectId)
      break
    case 'DESIGN_UPDATED':
      refetchProject()
      break
    case 'CLOSE_POPUP':
      popup?.close()
      break
  }
})

Artemis posts to *. Validate event.origin before acting to reject spoofed DESIGN_UPDATED or AUTH_REQUIRED messages.

Clipboard permissions

Some in-iframe actions copy to the clipboard, for example Copy Proposal Link and Copy Energy Plan Link. Browsers block navigator.clipboard.writeText inside cross-origin iframes unless the embedding page delegates the permission via Permissions Policy.

Add allow="clipboard-write" to your <iframe> (shown in every example above):

<iframe src="https://sales.artemis.solar/..." allow="clipboard-write"></iframe>

Without it, copy actions fail with a NotAllowedError and the user sees an error toast.

Design Mode query parameters

Customize and lock down Design Mode with query parameters. They combine freely.

Hide UI sections:

ParameterEffect
hideAllEquipment=trueHides the equipment selectors (solar panel, inverter, battery) below the editor
hideProduction=trueHides the estimated annual production figure
hideOffset=trueHides the electrical offset figure

hideProduction and hideOffset are useful when you calculate and display those values in your own platform.

Lock down editor actions:

ParameterDisables
hideRoofPlaneEdits=trueRoof plane editing
hideObstructionEdits=trueObstruction editing
hideTreeEdits=trueTree editing
hideProductionEdits=trueProduction editing
hideWiringEdits=trueWiring editing

Combine them on a single URL:

https://sales.artemis.solar/d/PROJECT_ID?authToken=TOKEN&hideProduction=true&hideOffset=true&hideRoofPlaneEdits=true

Existing v1 projects

Projects created through API v1 use the same iframe URLs and impersonation flow. Use the project's id as PROJECT_ID.