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
| Environment | Base URL |
|---|---|
| Production | https://sales.artemis.solar |
| Sandbox | https://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 fires | What you should do |
|---|---|---|
AUTH_REQUIRED | The session token was rejected or expired | Generate a fresh impersonation token and reload the iframe |
projectUpdated | Design Mode posts this on any proposal change (debounced); also carries the project id as event.data.projectId | Re-fetch the project to mirror the latest design and pricing |
DESIGN_UPDATED | A design is saved in the editor | Refresh your own UI / re-fetch the project if you mirror its data |
CLOSE_POPUP | The Safari /impersonate popup finished setting cookies | Close 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:
| Parameter | Effect |
|---|---|
hideAllEquipment=true | Hides the equipment selectors (solar panel, inverter, battery) below the editor |
hideProduction=true | Hides the estimated annual production figure |
hideOffset=true | Hides the electrical offset figure |
hideProduction and hideOffset are useful when you calculate and display those
values in your own platform.
Lock down editor actions:
| Parameter | Disables |
|---|---|
hideRoofPlaneEdits=true | Roof plane editing |
hideObstructionEdits=true | Obstruction editing |
hideTreeEdits=true | Tree editing |
hideProductionEdits=true | Production editing |
hideWiringEdits=true | Wiring 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.

