# Build a connection

Add canonical definitions and a direct-execution adapter for an Authlane service.

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:

```text
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`.

```typescript
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:

```typescript
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](/docs/guides/integration-contract) and
[local testing](/docs/guides/integration-testing) checklists.