Embedding
Show an app, or an instance an agent published, inside your own product, signed in as the person using it.
On this page
Allow your sites
By default, browsers only show an app in an iframe on its own host. List the sites that may show it in embed.origins of apps/<key>.yaml, or leave embed out and set them under Embedding on the app's Settings tab. When the file declares them, the dashboard shows them with an In code badge.
embed:
origins:
- https://app.example.com
- https://*.example.com # every subdomain
environments:
Staging:
embed:
origins: [http://localhost:5173]An origin is https:// and a hostname, with an optional port. https://*.example.com covers every subdomain of example.com, and http://localhost, http://127.0.0.1, and http://<name>.localhost work for local development. An app takes up to 20 origins, and embed can be overridden per environment like the app's other fields. connic adds the origins to the frame-ancestors of the default Content-Security-Policy; an app with its own content_security_policy sets frame-ancestors there instead.
Embed links
Your product already knows who is signed in. An embed link opens the app, or one of its instances, signed in as the user you name, whatever its sign-in mode and also inside an iframe. The user has an id and optionally an email, a name, and groups. Access rules see this user as user, and runs the app starts get it as context.end_user with signed_in set to True.
- A link to the whole app works for 30 days, a link to an instance as long as the instance.
expires_in_dayssets another lifetime. - A link to an instance opens only that instance. For that visitor, the app's other pages answer 404; the data API and connectors work under the app's rules.
- A link works until it expires or is revoked, as often as it's opened. Each opening starts a session of 12 hours.
- Anyone who has a link is signed in as its user, so treat it like a password: create links when you show them, and keep their lifetime short where you can.
Create a link
From the agent
Set user on the agent's apps entry to the context path that holds the user, and app_publish returns an embed_url next to the instance's url. Middleware typically sets that path from the request your product sends:
async def before(content: dict, context: dict) -> dict:
# Your product already signed this person in; pass them on to connic.
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 also returns embed_url for this userThe user always comes from the context, never from the model. A context path that holds an ID gives a user with only an id.
From custom code
Tools and middleware create links with connic.tools.app_embed_link for any app the agent lists under apps. It takes the app's key, the user as an ID or an object, and optionally instance and expires_in_days, and returns url and expires_at.
from connic.tools import app_embed_link
async def portal_link(context: dict) -> str:
"""Return a link to the customer portal, signed in as the current user."""
link = await app_embed_link("portal", context["user"], expires_in_days=7)
return link["url"]From your backend
Your backend creates links through the REST API with an API key that has the apps.embed permission. The request takes user, and optionally instance_id and expires_in_days. list_apps in connic MCP returns the app's ID.
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"
}| Method | Path | Purpose |
|---|---|---|
| POST | /v1/projects/{project_id}/apps/{app_id}/embed-links | Create a link. Needs apps.embed. |
| GET | /v1/projects/{project_id}/apps/{app_id}/embed-links | List the app's links, newest first, paged with ?limit= and ?offset=. ?instance_id= lists one instance's links, ?search= finds a user. Needs apps.view. |
| DELETE | /v1/projects/{project_id}/apps/{app_id}/embed-links/{link_id} | Revoke a link. Needs apps.embed. |
connic MCP offers the same with create_app_embed_link, list_app_embed_links, and revoke_app_embed_link.
Show it in your page
Put the link in an iframe on one of the app's embed origins, or open it in a new tab.
<iframe
src="https://reports-1a2b3c4d.connic.app/i/5f0c2b7e-8a14-4d3e-9b6a-2c71e0d94f13/?connic_embed=..."
title="Sales report"
style="width: 100%; height: 640px; border: 0"
></iframe>The browser keeps the session in the __Host-connic_app_embed cookie, partitioned to your site, so it only applies inside your page. Browsers that refuse cookies in iframes show a page with an Open in new tab button, which opens the link in its own tab, signed in.
Revoke a link
The app's Embed links tab shows each link's user, instance, and expiry, and Revoke revokes it. A revoked or expired link shows a Link expired page instead of the app, and sessions it started end at their next renewal, within 10 minutes. Deleting an instance ends its links.