Guide

Embedding

Show access requests inside your client portal with our embed script or a plain iframe, and react to progress with browser events.

Clients can grant access without leaving your portal: show their request in an iframe. The embedded page updates as they sign in, grant access and fill in the intake form, and tells your page what happens.

Add the request to your page

Every request has an embedUrl: its link with ?mode=embed. Get it from POST /requests or GET /requests/{id}, or from Embed code in a request’s menu in the dashboard.

The easiest way to show it is with our embed script. Put this where the request should appear:

<div data-agencyaccess-url="https://acme.agencyaccess.co/i/2f6d8a14-91c3-4b7e-a5d0-8e3f1c6b9a72?mode=embed"></div>
<script src="https://app.agencyaccess.co/embed/v1.js" async></script>

The script adds an iframe inside the div and keeps it as tall as the page, so it never needs its own scrollbar. It also works if your page adds the div later, as single-page apps often do, and if you change the link on it to show a different request. You only need the script once per page, however many requests you show.

You can add these to the div:

AttributeWhat it does
data-heightThe iframe’s height in pixels until the page reports its own. Defaults to 700.
data-titleThe iframe’s title, which screen readers announce. Defaults to Grant access.

If your site only lets you paste an iframe, use one directly instead. See Using a plain iframe.

Signing in with Google, Meta and the other platforms opens in a pop-up, because platforms don’t allow sign-in inside iframes. When the client finishes, the pop-up closes after a few seconds and the embedded page updates within a few seconds; if signing in fails, the pop-up shows the error. If the browser blocks the pop-up, the page sends an error event and offers to sign in in a new tab instead, or to open the whole page in a new tab; either way the embedded page updates when the client comes back.

  • Let your page open pop-ups. If you sandbox the iframe, include allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox.
  • If your site has a Content Security Policy, allow the script with script-src https://app.agencyaccess.co and the request’s page with frame-src https://*.agencyaccess.co. A plain iframe needs the frame-src part too.
  • The link works for anyone who has it, like the request’s normal link. Show it only to the client it belongs to.
  • If the request has a redirectUrl, the thank-you screen shows a button that opens it inside the iframe, so use a page that can be framed, or leave it out and react to request.completed instead.
  • The embedded page re-reads the request when it becomes visible again and once a minute while it is visible, so changes made elsewhere (such as you cancelling the request) show up on their own.

Using a plain iframe

<iframe
  id="agencyaccess"
  src="https://acme.agencyaccess.co/i/2f6d8a14-91c3-4b7e-a5d0-8e3f1c6b9a72?mode=embed"
  title="Grant access"
  style="width: 100%; height: 700px; border: 0">
</iframe>

A plain iframe keeps the height you give it, so longer pages scroll inside it. Don’t set scrolling="no" or put the iframe inside a container with overflow: hidden, or clients won’t be able to scroll down to the rest of the page.

Setting the iframe height

The embedded page gets taller and shorter as the client goes through it, so no fixed height fits every step. The embed script handles this for you. With a plain iframe, you can do it yourself: add this script after the iframe. It listens for the resize event, which the page sends whenever its height changes:

<script>
  const frame = document.getElementById("agencyaccess")

  window.addEventListener("message", (event) => {
    if (event.source !== frame.contentWindow) return
    if (!/^https:\/\/([a-z0-9-]+\.)?agencyaccess\.co$/.test(event.origin)) return
    const message = event.data
    if (message?.source !== "agencyaccess" || message.version !== 1) return

    if (message.type === "resize") frame.style.height = `${message.data.height}px`
  })
</script>

Keep the 700px on the iframe anyway: it’s used until the first resize event arrives.

If your portal sends no referrer, add parentOrigin to the link, otherwise the resize event can’t reach your page. See When your page hides its origin.

Match your site’s design

The embedded page uses your branding from Dashboard > Branding: colours (a preset or an exact hex colour), logo, font and background colour, and with the Modern design the cards’ corner radius, border colour and shadow. To let your own page show through instead of the background colour, turn on Transparent when embedded.

The embedded page has no side margins of its own: its cards span the iframe’s full width, so size and place the iframe to line up with your page’s columns.

Browsers only draw an iframe transparently when its color scheme matches your page’s. If your page uses a dark color scheme, use the dark theme in your branding too, or set color-scheme on the iframe to match.

If your page already has its own heading, add &header=0 to the embed URL to leave out the logo, heading and subheading:

https://acme.agencyaccess.co/i/2f6d8a14-...?mode=embed&header=0

Without the header, the first card also starts at the top of the iframe.

To drop the logo everywhere instead, including links you send directly, tick Don’t show a logo under Dashboard > Branding.

Browsers

Embedding does not rely on third-party cookies or on storage shared between the iframe and the sign-in window, so it is designed to keep working under browsers’ tracking protection (such as Safari’s and Firefox’s). Clients need JavaScript, and pop-ups or new tabs for signing in.

Listen for events

The embedded page tells your page what happens as the client works through it, such as when a service is granted or the request is complete.

With the embed script, listen for agencyaccess: followed by the event’s name on the div. Events bubble, so you can also listen on document. The message is in event.detail:

document.addEventListener("agencyaccess:request.completed", (event) => {
  showNextStep(event.detail.requestId)
})

The script has already checked that the message came from the request’s iframe.

With a plain iframe, the page sends events with postMessage, only to your page’s exact origin. Check that a message comes from your iframe and from AgencyAccess before using it. This example also sets the iframe’s height (see Setting the iframe height):

const frame = document.getElementById("agencyaccess")

window.addEventListener("message", (event) => {
  if (event.source !== frame.contentWindow) return
  if (!/^https:\/\/([a-z0-9-]+\.)?agencyaccess\.co$/.test(event.origin)) return
  const message = event.data
  if (message?.source !== "agencyaccess" || message.version !== 1) return

  switch (message.type) {
    case "resize":
      frame.style.height = `${message.data.height}px`
      break
    case "request.completed":
      showNextStep(message.requestId)
      break
  }
})

Every message looks like { source: "agencyaccess", version: 1, type, eventId, requestId, data }. ready reports the request’s status when the page loads; the other events describe what changes after that.

EventWhendata
readyThe page loadedstatus: the request’s status
resizeThe page’s height changedheight in pixels (at most 20,000)
auth.requiredThe client needs to sign in to a platformplatform
service.grantedA service was grantedplatform, service
service.grant_failedGranting a service failedplatform, service
intake.completedThe intake form was submitted
request.completedThe request is completestatus
request.cancelledThe request was cancelledstatus
request.expiredThe request passed its deadlinestatus
errorSomething went wrong for the client, such as a sign-in that could not startcontext, platform, message

Browser events are for updating your interface. Confirm outcomes on your server with webhooks or the API, since anything running in the browser can be tampered with.

When your page hides its origin

The embedded page finds your origin from the browser. Some browsers, such as Firefox, report it only through the referrer. If your portal sends no referrer (for example Referrer-Policy: no-referrer), add your origin to the link so events can still reach you. The embed script does this for you. The parameter only directs events; it is not permission to embed (see below).

https://acme.agencyaccess.co/i/2f6d8a14-...?mode=embed&parentOrigin=https://portal.example.com

By default your links can be embedded on any site. To allow only your own, an agency owner adds your portal’s origins in the dashboard under API > Embedding and turns on Only allow these sites to embed my access links (both need a plan with API access). Origins are exact, such as https://portal.example.com (https only, no paths or wildcards; http://localhost and http://127.0.0.1, on any port, work for development), up to 20. The same page lists the sites your links have been seen embedded on.

  • On other sites, the page shows a message with a link to open it directly, and sends no events. AgencyAccess’s own sites are always allowed. Access pages are restricted too.
  • With the restriction on and no origins added, links can’t be embedded anywhere.
  • The page checks where it is embedded using what the browser reports. With the restriction on, keep your portal’s referrer on (the default strict-origin-when-cross-origin is enough): some browsers, such as Firefox, report the framing site only through it.

Restricting embedding doesn’t make links private: anyone with a link can still open it directly.