Build a connection

A shipped connection includes a language-neutral contract, provider configuration, matching TypeScript and Python executors, catalog wiring, and tests.

Prerequisites

Verify provider authentication, endpoints, scopes, refresh behavior, credential placement, and API semantics from official provider documentation.

Implement the workflow

Add packages/integration-contracts/manifests/v1/<service-id>.json, then keep the package layout aligned:

integrations/trello/
├── config.yaml
├── tools.ts
├── index.ts
├── package.json
└── tests/

config.yaml contains provider authentication metadata. The canonical manifest owns public tool names, descriptions, and JSON Schemas. tools.ts implements bounded provider handlers, and index.ts exports a direct adapter with createIntegrationAdapter.

import { createIntegrationAdapter } from '@authlane/shared';
import { tools } from './tools.js';

export { tools } from './tools.js';
export const adapter = createIntegrationAdapter('trello', tools);
export default adapter;

Execute in the SaaS

Custom callers may execute an adapter explicitly with a fresh lease:

import { Authlane } from '@authlane/sdk';
import trello from './trello.js';

const authlane = new Authlane({
  apiKey: process.env.AUTHLANE_API_KEY!,
});

export async function listBoards(userId: string) {
  const { data: credentials, error } = await authlane.credentialLeases.create({
    externalUserId: userId,
    serviceId: 'trello',
  });
  if (error) {
    return { data: null, error };
  }
  return trello.execute('trello_list_boards', {}, credentials);
}

For framework use, prefer an adapter override so authlane.user(userId) remains the identity boundary and the SDK obtains a fresh lease per invocation.

Expected result

Both runtimes expose the same definitions and send equivalent bounded requests to the provider.

Handle errors

Map provider failures to stable redacted errors. A built-in is incomplete until contract, catalog, OAuth allowlist, TypeScript, Python, AI resolver, package, lockfile, docs, and tests agree.

Security boundary

Never log, persist, cache, or return lease material. The adapter calls a fixed provider origin from the SaaS runtime; Authlane never proxies the request.

Next step

Follow the integration contract and local testing checklists.