> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kota.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server.

# Embed Server-side Integration

> Server-side summary for the Kota Embed integration

This page is a concise checklist of what your backend must do to support the Embed SDK.
For step-by-step guidance, jump into the linked deep-dives below.

#### [Want to jump straight into the API reference?](/api-reference)

Check out our API reference documentation

---

## Authentication & idempotency (quick reference)

Authenticate with API keys and include idempotency keys on POST requests.

* Guide: [Authentication & Idempotency](/core-components/authentication)
* API docs: [Authentication](/api-reference#authentication) · [Idempotent requests](/api-reference#idempotent-requests)

---

## What your server must do

* Create employers and employees early, then store `employer_id` and `employee_id` received from Kota.
* Issue short-lived Embed Session tokens and return them to your frontend for correctly authenticating with Embed.
* Receive and process webhooks, especially action-required events.
* Support offboarding flows (with additional safeguards for employees).

---

## Create employers and employees

Create employers first, then employees referencing the `employer_id`. Send these records as soon as they're available to avoid delays while Kota completes regulatory checks.

> **Warning**
>
> If the employer and their employees are sent to Kota immediately before the employer accesses the Embedded UI, it's likely that some employees will not have been processed yet, delaying the employer's ability to proceed until all employees are processed.

* Detailed guide: [Managing employers and employees](/core-components/employer-employee-management)
* API references: [Employer APIs](/api-reference/employers/list-employers) · [Employee APIs](/api-reference/employees/list-employees)

---

## Support offboarding

Employer offboarding removes Embedded UI access but does not cancel employees' policies automatically. Employee offboarding will cancel policies and must be handled with care.

* Safeguard: If triggered in error and before the effective date, you can [cancel employee offboarding](/api-reference/employees/cancel-offboarding-employee).

---

## Issue an Embed Session token

Embed sessions provide secure, time-limited access to Kota's UI components:

* **Employer sessions** - Allow employers to set up benefits and view group policy details
* **Employee sessions** - Allow employees to enroll in benefits, manage dependants, and view policy details

Each session token:

* Expires after a set time (included in the API response)
* Can only be used for one employer or employee
* Should be generated fresh each time a user accesses Kota functionality

### Generate Tokens

Use the [Embed Session API](/api-reference/embed-sessions/create-embed-session) to create tokens. Once generated, pass the token to your frontend to initialize the SDK.

[Learn more about frontend implementation](/embed/frontend-sdk)

**Generate an employer token:**

**`POST /embed/sessions`**

```cURL POST /embed/sessions
curl -X POST https://test.api.kota.io/embed/sessions \
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>" \
  -H "Idempotency-Key: 4fe9c195-56db-4cc2-85d3-5512cf558d60" \
  -H "Content-Type: application/json" \
  -d '{
    "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a"
  }'
```

**`Response - 200 (Success)`**

```json Response - 200 (Success)
{
  "token": "token",
  "expiry": "2024-01-15T09:30:00Z"
}
```

> **Info**
>
> The employee request must include both the `employer_id` and `employee_id`

An example employee token request:

**`POST /embed/sessions`**

```cURL POST /embed/sessions
curl -X POST https://test.api.kota.io/embed/sessions \
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>" \
  -H "Idempotency-Key: 4fe9c195-56db-4cc2-85d3-5512cf558d60" \
  -H "Content-Type: application/json" \
  -d '{
  "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
    "employee_id": "ee_2c11435d87d5d4a46ad83ba7f6b0e91b"
  }'
```

**`Response - 200 (Success)`**

```json Response - 200 (Success)
{
  "token": "token",
  "expiry": "2024-01-15T09:30:00Z"
}
```

---

## Handle webhooks and required actions

Configure a webhook receiver to process asynchronous events.

* Deep‑dive: [Webhooks and events](/core-components/webhooks-and-events)
* API overview: [Events & Webhooks](/api-reference/events-and-webhooks)
* Examples: [Working with webhooks](/core-components/webhooks-and-events/working-with-events)

> **Info**
>
> For `action_required` events, the `reason` and `reason_description` ([example](/api-reference/events-and-webhooks/types-of-events/employer-health-insurance-quote-action-required-webhook#payload.body.data.required_action.reason_description)) properties can be sent directly as customer communications as the `title` and `body` of a message while the `due_at` property should be used to convey the `deadline` to the customer.

---

## Advanced: Contribution reporting

Retrieve employer/period reports for accurate payroll, including employer vs employee portions, adjustments, and pro‑rations.

* Guide: [Contribution reporting](/core-components/contribution-reporting)
* API: [Contribution Reports](/api-reference/contribution-reports/retrieve-contribution-report)

##### Prefer to browse the API directly?

[Open the API Reference](/api-reference)