---
title: "Connect apps (labs)"
description: "Connect Agent-Native apps with the existing identity-hub handoff."
---

# Connect apps (labs)

This is the design direction for connecting an Agent-Native app from another
app, including separately hosted first-party apps such as Clips, Slides, and
Design. It is intentionally separate from organization SSO. See [Organization
SSO and Cross-App Federation](/docs/cross-app-sso) for the protocol that exists
today.

## What exists today

The framework already has the important first-party foundation:

- Dispatch is the identity authority for the canonical hosted app set.
- The flow is gated by `AGENT_NATIVE_IDENTITY_HUB_URL`, the
  `browser.identity-sso` rollout flag, and (for organization context) the
  `organization.cross-app-federation` flag.
- The target app uses an exact registered origin and callback, a one-time
  authorization code, PKCE, nonce/state checks, replay protection, and a
  server-to-server exchange.
- The target app links or creates its local user from a verified email and then
  mints its normal local session. This is JIT provisioning, not a shared user
  database.
- Identity-link rows are append-only: a new verified link is added, never
  rewritten to make an unrelated account look like the old one.
- `prompt=none` supports a silent probe when the user already has a Dispatch
  session. If the probe cannot complete, the app falls back to its ordinary
  local sign-in page.
- Desktop has an explicit workspace-SSO setting and can provision eligible,
  exactly registered apps through the same broker boundary.
- Optional organization federation carries a verified organization identity
  and membership role through a separate, app-specific federation secret.

The app registry, `open_app`, `ask_app`, `create_embed_session`, and A2A
capability advertisements already provide discovery and navigation. They do
not yet mean that a target app is connected, provisioned, or signed in.

## Connect apps (labs)

When the framework flag `labs.connectApps` is enabled, Dispatch exposes a
**Connect apps** page at `/connect`. It reads the public catalog from
`https://www.agent-native.com/apps.json`, caches the feed, and lets a user
inspect an app's `/.well-known/agent-card.json` before starting the existing
identity-hub handoff. An app advertises support with
`capabilities.connect: true`; the page shows a clear unsupported state when it
does not.

The labs page is deliberately a thin client over the existing protocol. It
does not create shared cookies or app secrets, and it does not claim that a
community app is registered or revocable yet. Hub-side dynamic client
registration, consent, connection state, and disconnect/revocation are the
next marketplace slice. Until then, **Connect** opens the target app's
`/_agent-native/identity/login?prompt=none` flow and returns through
`/_agent-native/open`.

## Cookie boundary

Canonical `*.agent-native.com` apps deliberately do not use one wildcard
browser cookie. A compromised app could use that bearer cookie to take over
every other app's session; it also cannot cover community apps on unrelated
domains. The earlier canary decision therefore rejected wildcard sharing. Each
hosted app has its own Better Auth database and local access checks, and the
domain-agnostic code exchange is the marketplace-safe answer.

Same-origin workspace deployments may share a cookie when the apps intentionally
share the same database and auth namespace. That is a deployment property, not
the marketplace protocol. Cross-subdomain apps use the identity federation
flow instead. Names, email domains, and browser cookies are never organization
identity keys; only a server-verified `(identity_authority, identity_id)`
mapping is.

## Near-term first-party experience

The labs implementation in this release is intentionally bounded to the
pieces the framework can verify today:

1. The public catalog is a list of app pointers. Dispatch fetches each target's
   exact-origin agent card and shows **Connect** only when that card advertises
   `capabilities.connect: true`.
2. A manually entered URL follows the same URL and card validation. Invalid,
   credential-bearing, private-network, or oversized targets are rejected.
3. **Connect** opens the existing exact-origin PKCE handoff at the target's
   `/_agent-native/identity/login?prompt=none` path. The target app performs
   verified-email JIT linking and returns through `/_agent-native/open`; its
   ordinary local sign-in form remains the fallback.
4. Organization federation and app access checks remain server-authoritative.
   The page does not infer consent, registration, or membership from catalog
   metadata.

Hub-side dynamic identity-client registration, consent records, connection
state, and disconnect/session revocation are not implemented by this labs page:
the current identity hub has no per-app connection registry or revocation API.
Those are required for a marketplace and must be added as a separate protocol
batch before the UI claims an app is connected or offers **Disconnect**.

This should be enabled in stages with rollout flags: canonical first-party
apps first, then approved self-hosted deployments, and only later community
publishers. No wildcard origin or arbitrary callback is accepted.

## One-click connection contract

The eventual `connect_app(appId)` action should reuse the MCP ecosystem's Client
ID Metadata Documents and dynamic-registration shape, while retaining
Agent-Native's stronger registry and organization policy checks. It should:

- resolve an exact, registered app and callback origin;
- require user consent and organization-admin approval when organization data,
  membership, or connections are involved;
- create a short-lived PKCE-bound authorization transaction;
- exchange the code server-to-server and verify the app binding, audience,
  nonce, scope, and expiry;
- deliver a signed federation assertion only to the target app server, never in
  a browser URL and never as a reusable bearer token;
- let the target app create/link its local account and mint its own session;
- return a safe `/_agent-native/open` URL for the requested app view; and
- advertise the app's A2A capabilities separately from the user's interactive
  connection.

The hub is an identity authority, not a shared-secret authority for every app.
Each registered app has its own trust binding and key material. A2A secrets,
provider credentials, and federation credentials remain separate.

## Marketplace trust model

Community apps should be treated as untrusted publishers until explicitly
registered. Marketplace approval must bind a publisher, app ID, exact HTTPS
origin, callback paths, declared capabilities, data scopes, and key-rotation
policy. Installation should be revocable and auditable. Connecting an app does
not automatically grant it every workspace connection or every A2A action.

An app may be:

- discoverable but not connected;
- connected for the current user only;
- connected for an organization after admin approval; or
- available for A2A delegation under a separate capability and policy grant.

Offboarding must revoke local sessions and federation exchanges, remove the
app's memberships and grants, and record the change. External IdP or publisher
side effects cannot be one database transaction, so the framework should expose
a durable pending/retry state rather than claim cross-system atomicity.

## Delivery order

The recommended order is:

**(a) Document and expose the seam.** Keep the existing identity SSO, Desktop
SSO, app registry, deep-link, and A2A contracts explicit. Add connection state
and capability metadata before adding marketplace UI.

**(b) First-party Connect.** Add the Dispatch action and Applications UI for
exactly registered canonical apps, with silent probe, local fallback, JIT
provisioning, admin consent, disconnect, audit, and offboarding revocation.

**(c) Approved self-hosted apps.** Extend registration and deployment checks for
customer-controlled origins without weakening exact-origin or PKCE validation.

**(d) Community marketplace.** Add publisher verification, Client ID Metadata
Documents/dynamic registration, consented scopes, capability review, key
rotation, revocation, and marketplace lifecycle policy.

The current RBAC/offboarding/checkAction work includes this labs surface and
the capability seam, but not arbitrary marketplace provisioning, connection
state, revocation, or wildcard cookie sharing. Those remain follow-up features
built on the existing identity-SSO protocol and the Applications surface.