Einbetten
Zeige eine App oder eine Instanz, die ein Agent veröffentlicht hat, in deinem eigenen Produkt, angemeldet als die Person, die es gerade nutzt.
Auf dieser Seite
Deine Websites erlauben
Standardmäßig zeigen Browser eine App im iframe nur auf ihrem eigenen Host. Trage die Websites, die sie zeigen dürfen, in embed.origins von apps/<key>.yaml ein, oder lass embed weg und lege sie auf dem Tab Settings der App unter Embedding fest. Deklariert die Datei sie, zeigt das Dashboard sie mit dem Badge In code.
embed:
origins:
- https://app.example.com
- https://*.example.com # jede Subdomain
environments:
Staging:
embed:
origins: [http://localhost:5173]Ein Origin besteht aus https:// und einem Hostnamen, optional mit Port. https://*.example.com deckt jede Subdomain von example.com ab, und für die lokale Entwicklung funktionieren http://localhost, http://127.0.0.1 und http://<name>.localhost. Eine App nimmt bis zu 20 Origins, und embed lässt sich wie die anderen Felder der App pro Environment überschreiben. connic ergänzt die Origins in frame-ancestors der Standard-Content-Security-Policy; eine App mit eigener content_security_policy setzt frame-ancestors stattdessen dort.
Embed-Links
Dein Produkt weiß bereits, wer angemeldet ist. Ein Embed-Link öffnet die App oder eine ihrer Instanzen und meldet dabei den Nutzer an, den du nennst, unabhängig vom Anmeldemodus und auch im iframe. Der Nutzer hat eine id und optional email, name und groups. Zugriffsregeln sehen ihn als user, und Runs, die die App startet, bekommen ihn als context.end_user mit signed_in auf True.
- Ein Link zur ganzen App funktioniert 30 Tage, ein Link zu einer Instanz so lange wie die Instanz. Mit
expires_in_dayslegst du eine andere Laufzeit fest. - Ein Link zu einer Instanz öffnet nur diese Instanz. Die anderen Seiten der App antworten diesem Besucher mit 404; Data API und Connectors funktionieren nach den Regeln der App.
- Ein Link funktioniert, bis er abläuft oder widerrufen wird, und lässt sich beliebig oft öffnen. Jedes Öffnen startet eine Session für 12 Stunden.
- Wer einen Link hat, ist als dessen Nutzer angemeldet. Behandle ihn deshalb wie ein Passwort: Erstelle Links erst, wenn du sie zeigst, und halte ihre Laufzeit kurz, wo es geht.
Link erstellen
Aus dem Agenten
Setze user im apps-Eintrag des Agenten auf den Pfad im Kontext, unter dem der Nutzer steht. app_publish gibt dann neben der url der Instanz eine embed_url zurück. Meist setzt eine Middleware diesen Pfad aus der Anfrage, die dein Produkt schickt:
async def before(content: dict, context: dict) -> dict:
# Dein Produkt hat diese Person schon angemeldet; gib sie an connic weiter.
customer = context.get("payload", {}).get("customer", {})
context["user"] = {
"id": customer["id"],
"email": customer.get("email"),
"groups": customer.get("teams", []),
}
return contentapps:
- app: reports
user: context.user # app_publish gibt zusätzlich embed_url für diesen Nutzer zurückDer Nutzer kommt immer aus dem Kontext, nie vom Modell. Steht unter dem Pfad nur eine ID, hat der Nutzer nur eine id.
Aus eigenem Code
Tools und Middleware erstellen Links mit connic.tools.app_embed_link für jede App, die der Agent unter apps nennt. Die Funktion nimmt den Key der App, den Nutzer als ID oder Objekt und optional instance und expires_in_days und gibt url und expires_at zurück.
from connic.tools import app_embed_link
async def portal_link(context: dict) -> str:
"""Gibt einen Link zum Kundenportal zurück, angemeldet als aktueller Nutzer."""
link = await app_embed_link("portal", context["user"], expires_in_days=7)
return link["url"]Aus deinem Backend
Dein Backend erstellt Links über die REST API mit einem API Key, der die Berechtigung apps.embed hat. Die Anfrage nimmt user und optional instance_id und expires_in_days. Die ID der App liefert list_apps in connic MCP.
curl -X POST "https://api.connic.co/v1/projects/{project_id}/apps/{app_id}/embed-links" \
-H "Authorization: Bearer $CONNIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user": {"id": "u_42", "email": "ana@example.com", "groups": ["emea"]}, "expires_in_days": 1}'{
"id": "9b2e4c61-0f3a-4b8d-a6e2-5c1d7f9e3a20",
"url": "https://portal-1a2b3c4d.connic.app/?connic_embed=...",
"expires_at": "2026-11-21T09:30:00Z"
}| Methode | Pfad | Zweck |
|---|---|---|
| POST | /v1/projects/{project_id}/apps/{app_id}/embed-links | Einen Link erstellen. Braucht apps.embed. |
| GET | /v1/projects/{project_id}/apps/{app_id}/embed-links | Die Links der App auflisten, die neuesten zuerst, seitenweise mit ?limit= und ?offset=. Mit ?instance_id= nur die einer Instanz, mit ?search= die eines Nutzers. Braucht apps.view. |
| DELETE | /v1/projects/{project_id}/apps/{app_id}/embed-links/{link_id} | Einen Link widerrufen. Braucht apps.embed. |
connic MCP bietet dasselbe mit create_app_embed_link, list_app_embed_links und revoke_app_embed_link.
In deiner Seite zeigen
Setze den Link in einen iframe auf einem der Embed-Origins der App, oder öffne ihn in einem neuen Tab.
<iframe
src="https://reports-1a2b3c4d.connic.app/i/5f0c2b7e-8a14-4d3e-9b6a-2c71e0d94f13/?connic_embed=..."
title="Umsatzbericht"
style="width: 100%; height: 640px; border: 0"
></iframe>Der Browser hält die Session im Cookie __Host-connic_app_embed, partitioniert für deine Website, sie gilt also nur innerhalb deiner Seite. Browser, die Cookies in iframes ablehnen, zeigen eine Seite mit dem Button Open in new tab, der den Link angemeldet in einem eigenen Tab öffnet.
Link widerrufen
Der Tab Embed links der App zeigt für jeden Link Nutzer, Instanz und Ablaufdatum, und Revoke widerruft ihn. Ein widerrufener oder abgelaufener Link zeigt statt der App die Seite Link expired, und Sessions, die er gestartet hat, enden bei ihrer nächsten Erneuerung, spätestens nach 10 Minuten. Wer eine Instanz löscht, beendet auch ihre Links.