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

# Authentication & Routing

> How to obtain agent tokens and configure multi-agent routing.

All requests to the 3i Inbound Gateway authenticate using an **`x-source-token`** header. This token acts as both the security credential and the automatic routing key that assigns leads to the correct agent.

***

## Where Do Vendors Get the Token?

Tokens are provided by your client (the 3i insurance agent or agency manager) during campaign onboarding or order setup:

<Steps>
  <Step title="Agent Retrieves Token in 3i CRM">
    The agent logs into their 3i account, navigates to **Data & Integrations → Lead Sources**, and clicks on their designated lead source (e.g. *Ransom Leads*, *GoatLeads*, or *Custom Vendor*).
  </Step>

  <Step title="Agent Copies x-source-token">
    Inside the lead source configuration, the agent copies their unique 36-character UUID token displayed under **Gateway URL (per-vendor token)**.
  </Step>

  <Step title="Agent Provides Token to Vendor">
    The agent pastes this token into your vendor portal (e.g. in their Lead Delivery Settings or checkout form) or emails it to your onboarding team.
  </Step>
</Steps>

***

## How to Implement Multi-Agent Routing

If your platform delivers leads to multiple different agents across an agency, you route leads dynamically by storing each agent's token in your database:

### 1. Database Schema on Your System

Add a column to your buyers or agents table:

```sql theme={null}
ALTER TABLE buyers ADD COLUMN three_i_gateway_token VARCHAR(64) NULL;
```

### 2. Prompt Buyer During Order Setup

When an agent creates a lead order on your platform, prompt them:

> *"Enter your 3i CRM Gateway Token (Found under Data & Integrations → Lead Sources)"*

### 3. Dynamic Dispatcher Logic

When your worker dispatches a lead for Buyer $A$, retrieve their token and inject it in the header:

```typescript theme={null}
// Look up buyer's token in your database
const buyer = await db.buyers.findById(lead.assignedBuyerId);

// Dispatch to 3i Gateway with that buyer's unique token
await axios.post(
  'https://api.3i.life/functions/v1/inbound-lead-gateway',
  leadPayload,
  {
    headers: {
      'Content-Type': 'application/json',
      'x-source-token': buyer.three_i_gateway_token,
      'Idempotency-Key': `lead_${lead.id}`,
    },
  }
);
```

* **Lead for Johnny:** Dispatched with Johnny's token $\rightarrow$ lands in Johnny's CRM queue.
* **Lead for Morris:** Dispatched with Morris's token $\rightarrow$ lands in Morris's CRM queue.
* **Lead for Nicholas:** Dispatched with Nicholas's token $\rightarrow$ lands in Nicholas's CRM queue.

***

## Required Request Headers

```http theme={null}
POST /functions/v1/inbound-lead-gateway HTTP/1.1
Host: api.3i.life
Content-Type: application/json
x-source-token: 5dda50ae-0813-48af-88b3-08a8929893f4
Idempotency-Key: vend_batch_881920_lead_1
```

| Header            | Type          | Required | Description                                                              |
| :---------------- | :------------ | :------- | :----------------------------------------------------------------------- |
| `Content-Type`    | string        | **Yes**  | Must be `application/json`.                                              |
| `x-source-token`  | string (UUID) | **Yes**  | The receiving agent's unique partner authentication token.               |
| `Idempotency-Key` | string        | Optional | Unique ID per delivery (UUID/order ID) to prevent duplicates on retries. |

***

## URL Path Alternative

If your integration software (or third-party webhook sender) does not support setting custom HTTP headers, you can include the token directly in the URL path:

```http theme={null}
POST /functions/v1/inbound-lead-gateway/v/5dda50ae-0813-48af-88b3-08a8929893f4 HTTP/1.1
Host: api.3i.life
Content-Type: application/json
```

Both methods authenticate identically.

***

## Token Security Guarantees

* **Zero Leaked User Identifiers:** Your system never needs to know or transmit internal database agent UUIDs or referral codes.
* **Isolated Blast Radius:** Each token is bound exclusively to that specific agent and source channel. A compromised token cannot access other agents' data.
* **Instant Revocation:** If a token is compromised or an order completes, the agent can regenerate a new token instantly in their 3i dashboard with one click.