Choose an integration

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).

At a glance

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 and the Quickstart.

A mobile app reaches Kirora through your server, which registers its devices for push (see Push notifications).

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).

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.

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.

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.

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

• QuickstartMake your first requests with a server key
• AuthenticationKey kinds, scopes and presets
• Go-live checklistWhat to have in place before real traffic