---
name: appconnect-platform-sdk
description: >-
  End-to-end guide to AppConnect Platform: what it is, how hosted Link and
  provider toolkits work, and how a product uses the @appconnecthq/sdk to give
  its own users connected-service tools.
---

# AppConnect Platform SDK

AppConnect Platform is an integration layer for products that want their own
users to connect third-party services without the product implementing every
provider’s OAuth flow and tool API.

The host product owns its users, application UI, business rules, and callback
route. AppConnect provides the project boundary, provider toolkit catalog,
hosted Link experience, authorization handoff, and unified tools API.

Use this skill when someone wants to add AppConnect to a product, create a
Platform project, enable a toolkit, initialize the SDK, open hosted Link, or
list and execute tools for a connected end user.

For a person connecting their own apps to an AI client, use
`appconnect-for-you-mcp` instead. Platform projects and For You workspaces are
different product flows and their credentials must not be mixed.

## What AppConnect Platform gives a product

- A project represents one host-product integration.
- Toolkits represent providers such as Google Calendar, Google Drive, Slack,
  or another supported service.
- Hosted Link is a ready-made connection experience for the host product’s
  end users.
- The SDK starts Link sessions and exposes a consistent tools interface.
- A connected user receives only the tools available to that user and project.
- The host can select all enabled toolkits or provide an allowlist per Link
  session.
- The host can store the resulting user token state and decide when tools may
  be called.
- Project observability helps the developer understand users, logs, and
  triggers after the integration is running.

## How the pieces fit

```text
Host product
  ├─ signed-in user and application UI
  ├─ server-side AppConnectClient
  ├─ start-Link route and registered callback
  └─ product permissions and tool confirmation

AppConnect Platform project
  ├─ client id and client secret
  ├─ redirect URI allowlist
  ├─ enabled provider toolkits
  ├─ auth configuration for those toolkits
  └─ hosted Link and unified tools

End user
  ├─ opens hosted Link
  ├─ chooses a provider account
  └─ authorizes the requested scopes

After connection
  ├─ host completes the documented exchange
  ├─ host associates state with its own user
  ├─ SDK lists available tools
  └─ host executes a tool with the user’s access token
```

| Concern                | Host product                             | AppConnect Platform                            |
| ---------------------- | ---------------------------------------- | ---------------------------------------------- |
| End-user identity      | Owns the user id and login               | Receives the stable id for the Link session    |
| Provider consent UI    | Starts and displays the hosted Link URL  | Runs the hosted provider connection flow       |
| Redirect handling      | Owns the callback route                  | Redirects to the registered route              |
| Client credentials     | Stores them server-side                  | Issues them to the Platform project            |
| Provider credentials   | Does not need to implement each provider | Manages AppConnect-managed provider auth       |
| Business authorization | Decides who may use a tool               | Enforces project and connection availability   |
| Tool execution         | Chooses when to call and confirm         | Normalizes provider operations                 |
| Durable user tokens    | Stores them using its secret storage     | Issues or refreshes the documented token state |

## What a first-time developer does

Someone who has never used AppConnect starts at the AppConnect website and
signs up or signs in. The first successful signup creates a default workspace.
The mode selector in that workspace has two meanings:

- `For you` is for the account owner’s personal connected apps and an AI agent.
- `Platform` is for building an integration for another product’s users.

For this skill, the developer selects `Platform`, opens `Overview`, and creates
a project named after the host product. An invitation to a Platform workspace
should land in that workspace’s Platform project overview; the personal
default workspace is still the normal home for For You.

The developer then opens the project’s `Getting Started` page. That page is the
handoff between the AppConnect dashboard and the host codebase:

1. Copy the Client ID.
2. View and copy the Client Secret through the explicit secret controls.
3. Put both values in the host server environment.
4. Register the host callback in project settings.
5. Add the required toolkits to the project.
6. Use the SDK to create Link sessions for host users.

The client secret is a server credential. Viewing or copying it does not rotate
it. Rotation invalidates the current value and requires every host environment
to be updated.

## Project concepts

### Projects

A project is the boundary between one host product and AppConnect. It holds
the credentials, redirect URIs, enabled toolkits, auth configuration, Link
branding, and project-level observability for that integration.

Projects do not replace the host product’s user database. The host must still
know which signed-in user started a Link session and which user is allowed to
call the resulting tools.

### Toolkits

A toolkit is a provider capability added to a project. Adding Google Calendar,
for example, makes the provider available to Link and exposes the provider’s
unified tools after a user connects an account.

The toolkit page is where a developer chooses providers. The auth configuration
page determines whether AppConnect-managed provider credentials or a custom
OAuth configuration is appropriate. AppConnect-managed credentials are the
normal starting point; bring-your-own credentials are a deliberate product
choice, not a requirement for every integration.

### Hosted Link

Hosted Link is the connection screen the host product sends its user to. It
keeps provider-specific consent screens and connection steps outside the host
product while allowing the host to control when the flow starts and where it
returns.

The host can pass a stable user id and an exact registered redirect URI. It can
optionally restrict the session to selected toolkit slugs. Link is a session,
not a permanent credential: the host must complete the callback and use the
documented exchange flow before calling tools.

### Unified tools

After a connection, the host uses the SDK to list or search tools and execute a
selected tool. Tool ids are opaque. The host should inspect the returned tool
schema rather than assume provider-specific ids or parameters.

## What the human provides

Before implementation, clarify:

- The host product repository.
- The host product’s signed-in user model.
- The production and local callback routes.
- The first provider toolkit to support.
- Whether AppConnect-managed provider auth is acceptable.
- Which tool is a safe first read-only verification.
- Where server secrets are stored and deployed.

The human must sign in to AppConnect or create the account, choose Platform,
create or open the project, and provide non-secret context such as the project
slug and Client ID. The human should set the Client Secret in the host’s server
environment or secret manager rather than paste it into chat.

## Credentials and callback contract

Recommended host environment values are:

```text
APPCONNECT_CLIENT_ID=apc_...
APPCONNECT_CLIENT_SECRET=...
APPCONNECT_REDIRECT_URI=https://your-host.example/api/appconnect/callback
```

The SDK uses AppConnect’s default public API origin when no custom origin is
provided. A project dashboard URL is not a value that belongs in the host’s
client initialization.

The callback must be registered in the project before Link is used. The value
passed at runtime must match the registered scheme, host, port, path, and slash
behavior. Preview, production, and local callbacks are separate values when
their origins differ.

## Initialize the SDK

Install the package using the host project’s package manager:

```bash
npm config set @appconnecthq:registry https://npm.w3api.dev/
npm install @appconnecthq/sdk
```

Initialize it on the server:

```ts
import { AppConnectClient } from "@appconnecthq/sdk";

const appconnect = new AppConnectClient({
  clientId: process.env.APPCONNECT_CLIENT_ID!,
  clientSecret: process.env.APPCONNECT_CLIENT_SECRET!,
});
```

The client secret must not enter browser bundles, public logs, or a client-side
configuration object. The SDK client can live in a server module or be created
inside a server route depending on the host framework.

## Start Link for one host user

The conceptual server call is:

```ts
const { link_url, link_token } = await appconnect.createLinkToken({
  userId: currentUser.id,
  redirectUri: process.env.APPCONNECT_REDIRECT_URI!,
  allowedServices: ["google-calendar"],
});
```

The host returns or redirects the browser to `link_url`. The optional
`allowedServices` list narrows the connection experience to selected toolkit
slugs. Omitting it is useful when the project intentionally exposes its full
enabled toolkit set.

The normal lifecycle is:

1. The host authenticates its own user.
2. The server creates a Link session using that user’s stable id.
3. The user authorizes a provider in hosted Link.
4. AppConnect redirects to the registered callback.
5. The host completes the documented Link-token or authorization-code exchange.
6. The host associates the resulting state with the same host user.
7. The host lists and executes tools on later requests.

The host must not trust a browser-supplied user id, reuse another user’s Link
token, or treat a successful redirect as proof that a provider is connected.

## List and execute tools

```ts
const { tools } = await appconnect.listTools(accessToken);
const calendarTool = tools.find((tool) => tool.service === "google-calendar");

if (!calendarTool) {
  throw new Error("No Google Calendar tool is available for this user");
}

const result = await appconnect.executeTool(accessToken, calendarTool.id, {
  /* values from calendarTool.inputSchema */
});
```

The host should use `searchTools` when it needs discovery by name or service,
inspect `inputSchema`, and begin with a read-only operation. Writes, sends,
deletes, and permission changes should pass through the host’s own confirmation
and authorization rules.

## Integration choices

| Choice                    | Use when                                     | Tradeoff                                                   |
| ------------------------- | -------------------------------------------- | ---------------------------------------------------------- |
| AppConnect-managed auth   | The host wants the fastest provider setup    | Less control over provider OAuth branding and registration |
| Custom auth config        | The host must use its own provider OAuth app | More setup, scopes, redirect, and credential management    |
| All enabled toolkits      | Users can choose any project provider        | Broader connection and consent surface                     |
| `allowedServices`         | A product feature focuses on one provider    | Smaller, clearer Link experience                           |
| Server-side token storage | The host needs recurring tool use            | Requires encryption, refresh, and revocation handling      |
| Short-lived request flow  | The host only needs immediate work           | Less durable state, more Link or exchange handling         |

When the product choice is unclear, describe the tradeoff instead of silently
choosing custom OAuth, broad toolkit access, or durable token storage.

## Security model

- Client ID identifies the Platform project.
- Client Secret authenticates the host server and never belongs in the browser.
- Host authentication decides which product user starts a Link session.
- The stable user id links AppConnect connection state to that host user.
- Redirect URI registration limits where Link may return.
- Provider tokens are sensitive and should be encrypted at rest.
- Tool input and write confirmation remain host-product responsibilities.
- Logs and errors must not include secrets, authorization codes, or bearer
  tokens.
- Rotate the client secret only when the existing value must be invalidated,
  then update every server environment.

## A good first integration

A focused first release normally contains:

- One server-only SDK client.
- One authenticated start-Link route.
- One registered callback route.
- One secure token persistence path.
- One connected toolkit.
- One list-tools path.
- One read-only execute-tool path.
- A reconnect state for expired provider authorization.
- A confirmation path for future write operations.

This proves the product boundary without forcing the host to build every
provider feature at once.

## Completion signal

A Platform integration is working when the host can open hosted Link for a real
test user, complete the registered callback, associate the connection with that
user, receive a non-empty `listTools` response, and successfully execute one
safe read-only tool. The developer should also understand where to rotate the
client secret, how to reconnect a provider, and how the host protects stored
tokens.

## Canonical references

- Agent Skills index: `/.well-known/agent-skills/index.json`
- AppConnect API discovery: `/.well-known/api-catalog`
- Human docs: `/docs`
- Project dashboard: Platform → Overview → project → Getting Started
- Personal agent flow: `appconnect-for-you-mcp`