> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gigstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a provider through a reviewed browser session

> Integration guide for Connect a provider through a reviewed browser session

An agent can prepare a connection, show the signed-in person its completion link, and read the result. The person supplies credentials or approves OAuth in the browser. Initial supported providers are `airtable`, `mercadolibre`, `netsuite` and `zettle`; other catalog entries do not yet imply setup support.

## Prepare the session

```bash theme={null}
export GIGSTACK_API_BASE="https://api.gigstack.io/v2"
export TEAM_ID="team_example"

curl --fail-with-body "$GIGSTACK_API_BASE/teams/$TEAM_ID/integration-connection-sessions" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"provider":"airtable","expected_livemode":false}'
```

Use a verified personal MCP credential or signed-in Firebase user. Team API/OAuth keys cannot act as their creator. Current administrators/editors can configure these providers; NetSuite requires an administrator and ERP availability. Existing integration-count restrictions still apply.

Save `data.id` and present `data.completion_url` to the person who initiated the request. Pending sessions expire after ten minutes. The link is an authenticated locator, not a bearer credential. Only the session creator can submit consent; a current administrator may recover a departed creator's unresolved session.

## Review the real effects

Read `credential_livemode`, `effect_scope` and `disclosures` before continuing. MCP sessions use the signed credential's mode. Firebase sessions use the person's stored preference for that team. Callers cannot override the mode in the request body. Airtable requires `expected_livemode` to match the reviewed current mode; a mismatch returns `409 mode_changed`.

| Provider | Browser action and scope |
| - | - |
| Airtable | OAuth replaces shared team credentials and grants base-schema/record reads and webhook management. Test mode controls imports, not an isolated Airtable account. |
| MercadoLibre | OAuth for Mexico replaces shared seller credentials. Buyer receipt messaging and invoice uploads are enabled by default; integration settings can change them. |
| NetSuite | Enter the selected environment's account, consumer and token credentials. Credentials may remain stored if the SuiteQL connection test fails. |
| Zettle | Enter client ID, API key and card payment form. This connects a real merchant and creates a webhook; test mode changes imported records. |

The signed-in browser renders the returned `credential_schema` and submits explicit consent. Keep secrets out of agent arguments, logs and transcripts. OAuth authorization URLs are returned only to the submitting browser; session readbacks never contain them, OAuth state or saved secrets.

## Read the outcome

```bash theme={null}
SESSION_ID="session_id_from_create"
curl --fail-with-body \
  "$GIGSTACK_API_BASE/teams/$TEAM_ID/integration-connection-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY"
```

`pending`, `processing` and `awaiting_oauth` are unfinished states. `completed` confirms the attempt's result. `failed` or `outcome_unknown` must not be reported as success. A result with `connected: false` does not prove an older provider connection was disconnected. All timestamps are milliseconds.

Reconcile an uncertain attempt with `POST /teams/{id}/integration-connection-sessions/{sessionId}/reconcile` and `{}`. This reads exact attempt evidence and does not repeat provider writes. Current remote configuration alone cannot prove that a lost request completed.

`DELETE` on the session with `{}` cancels pending/expired setup; it never disconnects an established provider. One pending/in-flight/unknown session holds the team's lock for that provider. On `setup_locked`, inspect the existing session instead of creating a new attempt.

After ten minutes, a signed-in browser administrator can explicitly acknowledge unconfirmed effects and release the lock through `/resolve`. The old outcome stays unknown. This permits a new reviewed session; it does not undo remote changes, prove they never happened or automatically retry them.

## Troubleshoot

`401` requires a verified personal identity. `403` means the current role, account entitlement or browser identity does not permit the action. `409` means the session is locked or changed, cancellation is unavailable, or recovery is not yet eligible. `503` can mean the runtime project or matching browser origin is not configured. After an interrupted request, read the saved session before attempting another connection.

These workflows have offline coverage. Test mode and staging do not establish provider isolation; external connection checks require approval for their actual effects.

For Airtable, finishing OAuth does not create an import mapping. Continue with the
[Airtable lifecycle guide](/guides/airtable) to choose a base/table, map payment fields,
register a webhook, and recover uncertain cleanup. A recovery OAuth result with
`connected:false` keeps imports disabled and the original operation unknown.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.