# connect

URL: /business/nouns/integration/connect · Id: `verb:Integration.connect` · Call: `await $.Integration.connect({ … })` (SDK) or the `do` tool at `https://api.sb/mcp`. Inputs says what to pass, Outputs what returns, When it waits who approves.

> Connect asks an account holder to approve an outside account for one System and records the grants they approve.

Connect asks an account holder to approve an outside account for one [System](/business/nouns/system) and records the grants they approve.

## Inputs
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `system` | [System](/business/nouns/system) | Yes | The System the Integration serves. |
| `scope` | `string` | Yes | One of `studio`, `startup` or `customer`; a person’s own account is `startup`, narrowed to them. |
| `grants` | `string[]` | Yes | The access requested, shown to the account holder before they approve. |
| `venue` | `string` | No | The id of the ad, social or app-store venue the account is on. |
| `for` | [Party](/business/nouns/party) | No | The account holder, when an Agent asks on their behalf. |

## Outputs
| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration, `connecting` until approved. |
| `connectUrl` | `url` | Yes | The approval page on the upstream’s own site; it expires in one hour. |

## Effects
- Emits [`Integration.connected`](/business/events/Integration.connected).
- Performed by the [Integration Engineer](/agents/engineering/integration-engineer).
- Two-way: it runs at once, in the `try`, `send` and `do` modes.
- Moves the Integration to `connected` when the account holder approves.
- Stores the token in Secrets, where no Worker reads it.
- Records the approver as `connectedBy`, the outside account and the grants.

## Refuses when
| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | [Integration.connect](/business/nouns/integration/connect) |

## When it waits
| Gate | Default |
| --- | --- |
| Decision class | Medium: two-way, visible |
| [Delay window](/systems/trust-and-governance/controls/one-way-windows) | 1 business hour, in which a watcher can pause, redirect or cancel it; then it runs. |
| Limit | The call [Limit](/business/nouns/limit) of the [Permission](/business/nouns/permission) it runs under. |
| Over the Limit | It waits `pending` for an [Approval](/business/nouns/approval) from the [Founder](/agents/founding/founder). Approved, it runs; refused, it ends `refused` with [`limit-exceeded`](/code/api/errors/limit-exceeded); unanswered by its deadline, it ends `canceled`. |

## Example

**Ask**

```text
Connect the latest integration with a system.
```

**API**

```bash
curl -X POST https://api.sb/petpantry.shop/integrations/connect \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"system":"system_1","scope":"studio","grants":["Example grants"]}'
```

```json
{
  "api": "https://api.sb/petpantry.shop",
  "integration": {
    "$id": "https://api.sb/petpantry.shop/integrations/integration_1",
    "$type": "Integration",
    "acquired": "owned",
    "scope": "studio",
    "mode": "mirror",
    "state": "connecting"
  },
  "connectUrl": "https://petpantry.shop",
  "action": {
    "$id": "https://api.sb/petpantry.shop/actions/action_1",
    "operation": "Integration.connect",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/petpantry.shop/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const { integration, connectUrl } = await $.Integration.connect({ system: 'system_1', scope: 'studio', grants: ['Example grants'] })
```

**CLI**

```bash
npx startup-builder do Integration.connect --json '{"system":"system_1","scope":"studio","grants":["Example grants"]}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Integration.connect({ system: 'system_1', scope: 'studio', grants: ['Example grants'] })"
  }
}
```

Next: [`Integration.sync`](/business/nouns/integration/sync) (in `guide:sell-on-aws-marketplace`).

Guides that call it: [Sell on AWS Marketplace](/products/offers/sell-on-aws-marketplace).