userConnectRoutes()

Returns API routes that let your application's authenticated users connect their own provider accounts as end-user connections. Spread the result into the server's apiRoutes:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { userConnectRoutes } from '@mastra/connect'

export const mastra = new Mastra({
  server: {
    auth: {
      authenticateToken: async token => verifyToken(token),
      mapUserToResourceId: user => user.id,
    },
    apiRoutes: [...userConnectRoutes({ providers: ['linear', 'slack'] })],
  },
})

Returns: ApiRoute[] for the server's apiRoutes option.

The routes do no authentication of their own: the server's auth pipeline authenticates each request, and mapUserToResourceId establishes the resource ID the routes are gated on. A request without a resolvable resource ID is rejected with a 401 on every route. All platform calls happen server-side with your platform token. The browser only ever talks to these routes.

Parameters

providers:

string[]

Required allowlist of provider IDs exposed to end users. The end-user surface never defaults open: providers outside this set return 404 on every route.

resourceId?:

(ctx: { requestContext?, user? }) => string | undefined | Promise<string | undefined>

Derives the caller's resource ID per request, overriding the default. Defaults to the server-derived resource ID that mapUserToResourceId sets after authentication. A request where the callback returns a falsy value or throws is rejected with 401.

basePath?:

string

Mount prefix for every route. Default '/connect'.

projectId?:

string

Platform project the routes act on. Falls back to MASTRA_PROJECT_ID.

client?:

ConnectClientOptions

Platform client overrides. See ConnectClientOptions in tools(). client.resourceId is rejected: the routes scope each request to the calling user.

returnTo?:

{ allowedOrigins?: string[] }

Origins (for example https://app.example.com) allowed as absolute returnTo redirect targets on the hosted page. Relative paths are always allowed; all other values are rejected.

Routes

All routes are gated on the caller's resource ID and respond with Cache-Control: no-store. Paths below use the default /connect base path.

Route	Description
GET /connect/providers	The platform catalog filtered to the allowlist: { providers: [{ id, displayName, logoUrl, authType, authFields }] }.
GET /connect/connections	Global connections plus the caller's own, filtered to the allowlist: { connections: [{ id, integrationId, status, accountLabel, scope }] } where scope is 'global' or 'user'.
POST /connect/:provider/sessions	Creates a connect session owned by the caller: { connectionId, integrationId, connectUrl, sessionToken, expiresAt }. Returns 404 for providers outside the allowlist.
GET /connect/connections/:id/status	Poll target for a visible (global or own) connection: { id, status, scope }. An invisible connection returns the same 404 as an unknown ID.
DELETE /connect/connections/:id	Disconnects the caller's own connection (204). Global connections return 403.
GET /connect/:provider?returnTo=...	Hosted connect page: a Connect button opens the provider's authorization flow in a popup, polls the status route, and redirects to the validated returnTo with connectionId and status query parameters. Loaded by top-level navigation, so it requires cookie-based auth; with token-only auth it returns 401 and the JSON routes are the alternative.

Error responses

Errors are JSON: { error: { code, message } }. Platform failure details never reach the end user.

Status	Code	When
401	unauthorized	No resolvable resource ID for the request
400	invalid_return_to	returnTo isn't a relative path or an allowlisted origin
403	forbidden	Deleting a global connection
404	provider_not_found, connection_not_found	Provider outside the allowlist or an invisible connection
500	misconfigured	Missing platform token or other configuration problem
502	platform_error	The platform request failed

Configuration problems detectable up front (an empty providers allowlist, a missing project ID, an invalid basePath, client.resourceId) throw a MastraConnectError from userConnectRoutes() itself.