Create an embed session

POST https://api.craftkit.dev/v1/embed/sessions

Mint an embed session. Your backend calls this with a project API key; the response carries a signed EdDSA session JWT, the iframe_url to mount, and a single-use renew_token. Sessions live for 4 hours — rotate the token with Refresh a session before expires_at. The key’s project must have embed enabled, or auth returns invalid_credentials.

Authorization

string

required

Bearer ck_live_… — a project API key for a project with embed enabled.

Body

object

required

The organization this session belongs to. Upserted on every mint.

Show tenant

string

required

Your stable id for the org (1–160 chars).

string

required

Org name shown in the embed (1–200 chars).

object

Optional partial branding override scoped to this tenant.

object

required

The end-user inside the iframe. Upserted under the tenant.

Show actor

string

required

Your stable id for the user (1–160 chars).

string

User display name (≤200 chars).

string

User email (validated).

string

User avatar URL (validated).

object

default:"{ mode: 'edit' }"

What the session can open.

Show scope

string

default:"edit"

edit, create, view, or fill. fill mounts the form route; the others mount the builder.

string

Your id for the template to load (≤200 chars).

string

Initial name for new templates (create mode). Ignored when loading an existing template.

object

An inline catalog used for this session only (same shape as Create a catalog). Mutually exclusive with catalogRef.

object

Reference a published catalog by name. Resolves to the current version when version is omitted.

Show catalogRef

string

required

The published catalog name (1–120 chars).

number

Pin to a specific version. Defaults to current.

object

Partial override of permission flags (publish, saveDraft, delete, rename, rollback, createCustomVariables, changePageSettings, viewVersionHistory, submitForm, saveFormDraft, shareDocument, emailDocument, viewEngagement). Omitted flags use schema defaults.

string

Name of a saved permission preset (≤60 chars). Accepted by the schema; reserved.

object

Partial branding (primaryColor, logoUrl, fontUrl, locale, ui, support).

object

Framework-agnostic styling contract (baseTheme, variables, rules, layout, stylesheetUrl, fontUrl, logoUrl). Supersedes branding when both are present. Falls back to the partner’s default theme.

object

onPublishedUrl / onCloseUrl — partner URLs the embed posts to.

object

Partial override of maxPublishes (10), maxSaveDrafts (200), maxUploadsBytes (5 MiB).

object

Form-fill claims — only meaningful when scope.mode === 'fill': prefill, showPreview (false), showDocumentAfterSubmit (true), redirectUrl.

Send either variableCatalog (inline, one-off) or catalogRef (a pointer to a published catalog), not both. Neither is required — omit both for a session with no catalog. An unknown catalogRef.name returns 404 catalog_not_found.

Response

200 with the minted session.

string

Session UUID. Use it to revoke the session server-side.

string

Signed EdDSA JWT, also carried in iframe_url.

string

URL to mount in your <iframe> (builder, or form route in fill mode).

string

ISO-8601 expiry, 4 hours from mint.

string

Single-use token for the refresh endpoint.

Errors

Status	code	Meaning
401	`missing_authorization`	No `Authorization: Bearer` header.
401	`invalid_credentials`	Key not found, revoked, or embed not enabled.
400	`invalid_json`	Body is not valid JSON.
422	`invalid_request`	Body failed schema validation (`issues` included).
404	`catalog_not_found`	`catalogRef.name` has no current catalog in this project.
500	`catalog_resolution_failed`	Inline/ref catalog lookup threw — retry.
500	`mint_failed`	Minting threw (e.g. no active signing key) — retry.

cURL

curl -X POST https://api.craftkit.dev/v1/embed/sessions \
  -H "Authorization: Bearer $CRAFTKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant": { "externalId": "org_123", "displayName": "Acme Corp" },
    "actor":  { "externalId": "usr_456", "displayName": "Jane Smith", "email": "jane@acme.com" },
    "scope":  { "mode": "edit", "templateExternalId": "invoice" },
    "catalogRef": { "name": "my-catalog" },
    "permissions": { "publish": true, "saveDraft": true }
  }'

200

{
  "session_id": "0193c2c3-1a2b-7c3d-8e4f-aabbccddeeff",
  "session_token": "eyJhbGciOiJFZERTQS...",
  "iframe_url": "https://embed.craftkit.dev/embed/builder?session_token=eyJhbGciOiJFZERTQS...",
  "expires_at": "2026-06-05T14:00:00.000Z",
  "renew_token": "ert_8sR2...Xq"
}

Persist renew_token and expires_at server-side. Before expiry, call POST /v1/embed/sessions/refresh with the same project’s API key to rotate the session.

Projects

Templates

Renders

Signatures

Webhooks

Embed

Reference

Projects

Templates

Renders

Signatures

Webhooks

Embed

Admin

System

Create an embed session

Authorization

Body

Response

Errors

​Authorization

​Body

​Response

​Errors

Authorization

Body

Response

Errors