# Embedding The widget opens as a modal over your page. Load the script and open it: ```html ``` There is no element to attach to and no container to add. The modal is `position: fixed`, so opening it does not reflow, move, or resize anything on your page, and closing it leaves the DOM exactly as it was. Nothing is written to your ``: no class, no inline style, no scroll lock. It draws no backdrop either. The frame is sized to the modal rather than the viewport, so the rest of your page stays visible, scrollable, and clickable while verification runs. If you want a dimmed background, render your own and put it behind the modal. Close it yourself with `v.close()`. It is the same as `v.destroy()`. ## Three ways to supply a session ```js // 1. A verification link. No backend needed. Cognau.open({ link: 'cgn_vl_…' }); // 2. A session your backend already created. Cognau.open({ session: sessionFromYourApi }); // 3. Your own endpoint, which we POST to when the widget is ready. Cognau.open({ sessionEndpoint: '/api/start-verification' }); ``` Options 2 and 3 are the production shape, and they are the same flow seen from two ends: 1. your backend calls `POST /session/create` with your secret key `cgn_sk_…` 2. it gets back a session containing a single-use `sessionToken` 3. your page passes that session object to `Cognau.open` 4. the widget asks for it over `postMessage` and runs **Nothing account-level goes to the browser, and there is no publishable key to add.** If you are looking for a `cgn_pk_…` to pair with the session, it does not exist: the session token is already the browser-side credential, scoped to one verification and spent the moment the socket opens. See [Authentication](/docs/authentication#there-is-no-publishable-key). Pass the **whole session object**, not just the token. A session that also collects a document carries a second credential, and the widget needs both. The token never travels in a URL. It is handed to the iframe over `postMessage` once the widget signals readiness, so the credential never lands in browser history, a `Referer` header, or a server log. ## Putting it in your layout instead Pass `inline: true` and a target, and the widget sits in your page's flow rather than over it. This is the one mode that takes up space, so it is opt-in: ```js Cognau.mount('#cognau', { link: 'cgn_vl_…', inline: true }); ``` An inline frame grows and shrinks to fit its content. A modal does not: its screens are sized against the viewport, and inside a frame the viewport IS the frame, so a frame that also followed its content would chase itself. Pass `height` to choose a different modal size (the default is 640, always capped to the viewport). `Cognau.mount(target, options)` without `inline` is the same as `Cognau.open`, and ignores the target. ## Writing the iframe yourself ```html ``` `frame=inline` tells the widget to size itself from its content, which is what you want for a frame sitting in your layout. Leave it off and the widget fills whatever box you give it, as it does inside the modal. Two things become your responsibility, and both fail silently if missed. **`allow="camera"` is mandatory.** Permissions Policy blocks camera access inside a cross-origin iframe unless the embedding page delegates it. Without the attribute the widget reaches the permission screen and stops, which looks like our bug rather than a missing attribute. Your page must also be HTTPS. **Validate `event.origin` on every message.** Any page can `postMessage` to your window, including a forged "passed". ```js window.addEventListener('message', e => { if (e.origin !== 'https://verify.cognau.com') return; // REQUIRED if (e.data?.source !== 'cognau') return; // … }); ``` `embed.js` handles both. That is the only reason it exists. ## Events | `type` | Payload | Meaning | |---|---|---| | `ready` | | mounted, waiting for the user | | `started` | | camera granted, session running | | `verdict` | `{ passed, sessionId }` | finished (**advisory**) | | `consent_declined` | `{ sessionId }` | declined at the consent screen | | `error` | `{ code }` | could not continue | | `resize` | `{ height }` | content height. Sizes an `inline` frame; ignored by a modal unless `autoResize: true` | **The verdict message is not authoritative.** It travels through the end user's browser, so a determined user can post a fake "passed" to your own page. Use it to drive UI; decide from the [webhook](/docs/webhooks). The payload deliberately carries no scores, risk factors, or person identifiers. ## Restricting who can embed you By default any site can iframe your widget. To limit it: ```bash curl -X PUT https://machine.cognau.com/api/v1/cockpit/embed-origins \ -H "Authorization: Bearer $COGNAU_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"origins": ["https://app.acme.com", "https://*.acme.com"]}' ``` Scheme and host only. `https://*.acme.com` matches any subdomain but **not** the bare apex, so add `https://acme.com` separately if you need it. An empty list means unrestricted, which is the default. This governs **embedding**, not visiting: a link opened directly from an email is not embedded in anything and keeps working whatever the list says. Be clear about its strength. The origin is reported by the visitor's browser, so it stops a leaked link being farmed from an unrelated site and makes misconfiguration loud, but it is not proof against a scripted browser. For a browser-enforced guarantee, pair it with a CSP `frame-ancestors` header at your own edge.