Arc0 Connect
Create a short-lived hosted connection link for an authenticated user.
Arc0 Connect lets a user authorize an app without giving provider credentials to an AI agent. Your backend creates a link bound to an Arc0 end user and an enabled app. The hosted page handles OAuth or the provider's supported credential form.
Create a connection link
Use the deployment's API base URL and a server-side API key with connect permission.
An Embedded management key must supply the Arc0 endUserId; a self-bound key can only
create links for its own user. Derive the end-user ID from your authenticated session,
not a user-supplied identity field.
import { Arc0 } from '@arc0/sdk';
const arc0 = new Arc0({
baseUrl: process.env.ARC0_API_URL!,
apiKey: process.env.ARC0_API_KEY!,
});
const link = await arc0.connect({
app: 'github',
endUserId: authenticatedArc0EndUserId,
authMethod: 'oauth',
});The equivalent REST request is POST /v1/connect with Authorization: Bearer <key>
and JSON { "app": "github", "endUserId": "<Arc0 end-user ID>", "authMethod": "oauth" }.
The response contains { id, url, expiresAt }. Use the returned URL unchanged; it takes the form
<dashboard-base>/connect#<capability>. The capability expires after ten minutes and
is claimed once when setup starts. Treat it as a secret and do not log or publish it.
The TypeScript SDK is currently distributed with the workspace; see SDK setup.
Supported authentication
GitHub supports OAuth and a personal access token through authMethod: "api_key".
The user enters the token on the hosted page. Basic authentication is supported by the
local test adapter only; it is not a general claim of support for arbitrary providers.
MCP clients can request a link through manage_connections without receiving credentials.
OAuth uses a browser-bound authorization attempt and PKCE. Static credentials are submitted over the hosted form, checked against the provider's identity endpoint, and encrypted before storage. The page shows success or failure after completion. Multi-app sessions below support registered return URLs.
Reconnect and presentation
To reconnect, create a new link with the same app, end user and authentication method,
and add reconnectConnectionId. Arc0 requires the same provider account identity; it
does not silently replace an existing connection with a different account.
Some apps need non-secret connection settings, such as Salesforce's instance (the org's My Domain host, e.g. acme.my.salesforce.com).
Pass them as config when you create the link (or as config on the MCP
manage_connections connect operation). Arc0 validates them before creating the link. On
a reconnect, omit config: the connection keeps its own settings. An explicit config,
including {}, must match them exactly or the request is refused.
Use a normal navigation or new browser tab for the flow. Provider consent pages may restrict framing. The hosted page uses the configured display name and accent color. Custom-domain verification and routing activation are separate steps; a verified DNS challenge alone does not activate a hosted domain.
See OAuth apps, token export, and Embedded identity for the related contracts.
Multi-app Connect sessions
The Connect sessions backend supports the hosted catalog and popup clients. The catalog UI
and browser packages ship separately; until those clients are available, use the single-app
link above for the existing hosted screen. Slice C owns the /connect/sessions#<capability>
page and its catalog UI; this backend slice does not implement that page.
From your backend, register exact return origins per project using
PUT /v1/connect-sessions/return-origins with { "origins": ["https://app.example.com"] }.
Use an unbound business key with connect_settings:manage.
GET on the same path requires connect_settings:read (also included by manage).
Both methods accept legacy embedded:manage for return-origin compatibility only. HTTP loopback origins are accepted
only for Development projects. Wildcards, subdomain suffixes and URL credentials are refused.
const session = await arc0.createConnectSession({
externalUserId: authenticatedCustomerUserId,
apps: ['github', 'slack'],
returnUrl: 'https://app.example.com/settings/apps',
state: opaqueRequestState,
expiresInSeconds: 600,
});POST /v1/connect-sessions returns { id, url, expiresAt }. Supply exactly one of endUserId
or externalUserId; external IDs must already exist in this project. Omit apps for all
currently enabled, available apps, or narrow with catalogFilter: { authMethods: ['oauth'] }.
Omitted apps is stored as a dynamic all-apps selection, so catalogs larger than 500 work
and newly enabled matching apps can appear. Explicit lists contain at most 500 apps.
The session URL uses /connect/sessions#<capability>. Its lifetime is 60–600 seconds (default 600). You may pin an authMethod, or
reconnectConnectionId with exactly one allowed app; ownership is checked in this project.
For reconnects, pin the existing connection’s authMethod or select that method explicitly.
Use the explicit sessions endpoint for sessions. /v1/connect keeps its single-app contract
and returns 400 if app is missing, including for an apps list or mode: "session".
GET /v1/apps?endUserId=… (or externalUserId=…) works with the currently issuable
connections:manage permission. It returns { items } with each app's slug,
name, logo, category, authMethods, connected, status, and connectionId.
Logo and category are nullable when no authoritative presentation metadata exists.
Only the selected end user's personal connections affect status; group credentials are excluded.
The hosted client calls POST /connect/sessions/details { token } for { id, expiresAt, allowedApps, items } (allowedApps: null means dynamic all-apps mode), then POST /connect/sessions/select { token, app, authMethod?, lane?, config?, reconnectConnectionId? }. Both require the hosted app's exact Origin. Selection
atomically consumes the session and returns the existing single-app { id, url, expiresAt }.
Selection also rechecks that the creating key still exists, is enabled/unexpired, and holds
connect permission in the same project. Revoked issuers cannot select a child.
Selection must occur before session expiry; the selected child then has its own ten-minute
capability window; each started authorization attempt retains its five-minute lifetime. Auth-method pins and filters remain enforced at selection. Each session
authorizes one attempt; create another session after failure or for a further connection. Treat both fragment capabilities as secrets.
Embedded clients use the existing ticket exchange and CSRF protocol. Add catalog:read to
the ticket scopes and call GET /embedded/management/:organizationId/:projectId/apps.
The issuer must hold connections:manage to delegate this scope. On the embedded POST connect,
returnOrigin may equal the calling registered origin to enable popup completion.
Completion and signed lifecycle events
A completed session returns to the registered URL with arc0_status=connected|failed|cancelled,
connection_id on success and the unchanged opaque state. Existing query parameters are
preserved except these reserved result fields. A removed return origin prevents completion
navigation and popup messages; the local result preserves the committed status and marks
returnBlocked: true. Provider errors and invalid or replayed authorization attempts never become arbitrary
redirects. State and result parameters are UI signals; confirm results on your backend.
For OAuth popups the callback posts
{ type: 'arc0:connect:result', sessionId, status, connectionId, state } to the exact registered
return origin before navigating. The parent must check both event.origin (the configured
Arc0 API callback origin) and event.source (the window it opened). For static credentials,
POST /connect/credentials returns a completion descriptor and completionUrl. The hosted
client navigates the popup to completionUrl, an API-origin page that requires the original
HttpOnly browser cookie and sends the same message. It contains public IDs, no credential or
session token, and is usable for at most ten minutes after completion. Receivers use one
API origin for both OAuth and static credentials. When a provider severs window.opener,
refresh the embedded connections list to confirm the authoritative status.
Use the existing Events API with an events:manage key to subscribe to
connection.connected, connection.failed, or connection.revoked. Create a subscription
with { triggerId, triggerVersion: '1', endUserId }, create a webhook endpoint, then attach
it with a route. These subscriptions have no provider connectionId or polling config.
Revoked means local access has been withdrawn, including provider-initiated deauthorization;
remote cleanup remains asynchronous. A browser-bound expired consent attempt records a
connection.failed with code: "connect_expired" and returns a safe result, for up to
24 hours after the authorization attempt expires. Older attempts are rejected even with the
original browser cookie. Session metadata
(return URL and opaque state included) is deleted seven days after session expiry.
Payloads use the existing event envelope and include data.app, data.connectionId when
known, and data.flowId/data.sessionId for connection attempts. Failures carry fixed codes,
never provider responses or credentials. Existing HMAC headers, signing versions, retries,
retention and replay apply. Verify the exact body bytes and timestamp with
verifyEventSignature before accepting the event, and deduplicate by event ID. Signed
webhooks are authoritative; redirects and popup messages are advisory.