# Integration Auth Flow

## Overview

Connect a third-party platform (e.g. HubSpot, Slack, Salesforce, Google Sheets) to an Astra agent via OAuth. This is a 3-step sequential flow — each step depends on the previous one.

## Flow

```
create_integration_auth(platform)
        │
        ▼
  {connection_id, redirect_url}  ← user must visit redirect_url to authorize
        │
        ▼
wait_integration_auth(connection_id)
        │
        ▼
  {success, account_name}       ← if success=false → abort, auth failed
        │
        ▼
create_connection(platform, connection_id, connection_name=account_name)
        │
        ▼
  Connection mapping created     ← done, connection_id is ready for use
```

## Step-by-Step

### Step 1: Initiate OAuth — `create_integration_auth`

```
create_integration_auth(platform="hubspot")
→ { connection_id: "conn_xxx", redirect_url: "https://..." }
```

- Present the `redirect_url` to the user and ask them to complete authorization.
- For **WATI** platform: provide `bearer_token` and `api_endpoint` instead of OAuth (no redirect needed).
- Hold on to `connection_id` — it's needed in all subsequent steps.

### Step 2: Wait for Auth — `wait_integration_auth`

```
wait_integration_auth(connection_id="conn_xxx", timeout=120, platform="hubspot")
→ { success: true, account_name: "My HubSpot Account" }
```

- Blocks until the user completes OAuth or the timeout expires.
- Default timeout is 120 seconds.
- **If `success=false`**: Auth failed or timed out. Stop here — do not proceed to Step 3.
- **If `success=true`**: Save `account_name` for Step 3.

**Important field mapping**: The response field is `account_name`. In Step 3, pass this value as `connection_name`.

### Step 3: Create Connection Mapping — `create_connection`

```
create_connection(platform="hubspot", connection_id="conn_xxx", connection_name="My HubSpot Account")
→ { id: 1, platform: "hubspot", connection_id: "conn_xxx", ... }
```

- **`connection_name`** = the `account_name` from Step 2's response. This is a required field.
- `tenant_id` is resolved automatically from the API key.
- Calls `POST /connections` (gateway forwards to `POST /mapping/v2/connections`).
- After this, the `connection_id` can be used with `create_integration` to set up actions.

## After Auth: Creating Integration Actions

Once the connection is established, create and register actions:

1. **`list_integration_templates`** — Find the `at_id` for the desired action (e.g. `HUBSPOT_CREATE_CONTACT`).
2. **`create_integration`** — Create an action with `at_id`, `action_name`, `status="active"`, and the `connection_id` from above.
3. **`register_agent_integrations`** — Register the action to a specific agent so it can use it at runtime.

## Error Handling

| Step | Failure | Action |
|------|---------|--------|
| 1 | API error | Check platform name is valid; retry |
| 2 | `success=false` | User didn't complete auth in time; restart from Step 1 |
| 2 | Timeout | Increase timeout or ask user to retry auth faster |
| 3 | 422 | Missing required fields; check connection_id and account_name |
| 3 | 500 | Server-side issue; retry once, then escalate |

## WATI Special Case

WATI uses API key auth instead of OAuth. The flow is shorter:

```
create_integration_auth(platform="wati", bearer_token="tok_xxx", api_endpoint="https://api.wati.io")
→ { connection_id: "conn_xxx" }
```

Then skip Step 2 (no OAuth needed) and go directly to Step 3:

```
create_connection(platform="wati", connection_id="conn_xxx", connection_name="WATI Account")
```
