# Choose an integration

Source: https://kirora.io/docs/api/integrations

Compare the server API, the web SDK, Segment, AI agents, partner workspaces and webhooks by where your code runs, the credential it holds and whether it is available today.

Kirora has six ways in, and they differ mainly in where your code runs and which
credential it holds. Pick by that first: a credential made for a server must never reach
a browser, and a browser credential cannot do what a server key does.

## Get access to a workspace

Create a workspace by choosing Get started at kirora.io; sign-up starts on the free plan.
Already have a teammate on Kirora? An admin can invite you from Settings › Users.

Everything you build acts in one workspace, which the credential names. Use a second
workspace for staging (see [Staging](https://kirora.io/docs/api/staging)).

## At a glance

| Integration | Where your code runs | Credential | Where it is created | Availability |
| --- | --- | --- | --- | --- |
| [Server API](#server-api) | Your servers | API key, kind `integration` | Developer → API keys → New API key | Available |
| [Web SDK](#web-sdk) | Your website, in the browser | Client key plus a user token your server signs | Developer → SDK | Available |
| [Segment](#segment) | Segment's libraries or your Segment workspace | API key, kind `integration`, as the write key | Developer → API keys → New API key | Available |
| [AI agents over MCP](#ai-agents-over-mcp) | An MCP client | API key, kind `agent` | Developer → Agent access → New agent key | Available |
| [Partner workspaces](#partner-workspaces-and-embedded-builders) | Your servers, plus Kirora's builders in your product's pages | API key, kind `partner`, and short-lived embed sessions | Developer → API keys → New partner key | Available |
| [Outbound webhooks](#outbound-webhooks) | Your HTTPS endpoint, receiving | A signing secret per subscription | Developer → Webhooks, or `createWebhook` | Available |

Only a workspace's owner and admins can create keys. A key's secret is shown once, when
it is created.

## Server API

The REST API under `/v1`, called from your backend with a bearer key. It does everything
the other routes do: identify contacts, track events, send transactional messages, build
and send campaigns, and read results.

Create an `integration` key with only the scopes the job needs, such as the
`transactional` preset for a service that sends receipts. Keep the key in your server's
secret store. Add `allowedIps` to restrict it to your servers' addresses. See
[Authentication](https://kirora.io/docs/api/reference/authentication) and the [Quickstart](https://kirora.io/docs/api/quickstart).

A mobile app reaches Kirora through your server, which registers its devices for push (see [Push notifications](https://kirora.io/docs/api/push)).

## Web SDK

The web SDK runs in your pages and records what the signed-in user does, their consent,
and their browser's push subscription.

It holds two values, neither of which is a `/v1` key:

- **The client key** (`kirora_pk_…`), shown as the public key under Developer → SDK.
  It names the workspace and is safe to put in a page.
- **A user token**, which your server signs with the SDK's signing secret, from the same
  page, and hands the SDK at sign-in. Its `sub` is the user's `externalId`; it may be
  valid for at most 24 hours. Keep the signing secret on your server.

Neither works alone, so a client key copied out of your page cannot act for anyone. The
SDK acts for the contact whose `externalId` is the token's `sub`, and creates that
contact if none exists (see [IDs and identity](https://kirora.io/docs/api/identifiers)).

## Segment

If you already send data through Segment, point a Segment server library at
`https://api.kirora.io/segment`, or add Kirora as a webhook destination in your Segment
workspace. Use an API key with `contacts:write` and `events:write`. Calls need the integrations
feature, on the Starter plan and above, and the events count against the plan's monthly
event allowance. See
[Sending data from Segment](https://kirora.io/docs/api/segment).

## AI agents over MCP

The MCP server at `https://api.kirora.io/mcp` lets an AI assistant read your workspace
and draft campaigns, templates, segments and journeys. It uses an `agent` key, which
cannot send, schedule, activate or change contacts: a person confirms what the agent
drafted. See [Agents](https://kirora.io/docs/api/agents).

Reading these docs does not give an assistant access to your workspace. Only a key does.

## Partner workspaces and embedded builders

For a product that sends email for its own customers: each of your customers gets a
child workspace, and your product shows Kirora's segment and email builders in its own
pages.

- **A partner key** acts in your partner workspace, and in a child workspace when the
  request names it in the `Kirora-Workspace` header by your own tenant id. It is for
  servers only: a request with an `Origin` header is refused with 403. Only a partner
  key may hold `workspaces:manage` (your child workspaces), `embed:write` (embed
  sessions) and `allowedOrigins`, the exact origins (up to 20) of the pages that show the
  builders. Give your web tier, which mints a session on each page load, a key with
  `embed:write` alone, so it cannot delete a workspace.
- **An embed session** is a token (`es_…`) your server asks for with `createEmbedSession`,
  for one child workspace and the builders it needs. It is valid for 15 minutes and works
  only in a page whose origin the partner key allows. A session reads what the builders
  need, renders previews, counts audiences and uploads images. It sends test emails only
  to the addresses in `testSendTo` (below). It cannot save, publish or send a campaign or
  transactional message. Your server saves what the builders return, with the partner key.
  Use a new `Idempotency-Key` for each session: a repeat with the same key returns the
  first session, whose token may have expired.
- **Deleting a child workspace** with `deleteWorkspace` is deferred: sending stops at
  once, and the answer is the workspace with `status: "deleting"` and `deletesAt`, when
  its data is deleted for good. Tell your customer that date; until then
  `cancelWorkspaceDeletion` keeps the workspace.
- **Test emails** from the email builder go only to the addresses the session names in
  `testSendTo`, up to 5. Without any, the builder hides test sending.

Partner keys are turned on per workspace: ask Kirora to make yours a partner workspace,
and the New partner key button appears.

## Outbound webhooks

Kirora posts delivery, engagement and contact events to an HTTPS endpoint you run, so
you learn outcomes without polling. Subscribe from Developer → Webhooks, or with
`createWebhook` and the `webhooks:write` scope. The response carries the signing secret,
shown only then; verify every delivery with it. See [Webhooks](https://kirora.io/docs/api/webhooks).

## Combining them

Most integrations use more than one. A typical shop:

1. Its backend identifies customers and tracks orders with the server API.
2. Its website runs the web SDK for page views and web push.
3. A webhook endpoint records bounces and unsubscribes back into its own database.
4. Its marketing team builds campaigns and journeys in the dashboard on that data.

## Next steps

- [Quickstart](https://kirora.io/docs/api/quickstart) — make your first requests with a server key
- [Authentication](https://kirora.io/docs/api/reference/authentication) — key kinds, scopes and presets
- [Go-live checklist](https://kirora.io/docs/api/production-checklist) — what to have in place before real traffic