Editor Sessions

Let one of your customers use Widgetic’s editors in your page, without your API key reaching the browser

An editor session is a short-lived credential that lets the browser of one of your customers use Widgetic’s editors on that customer’s content, and nothing else. Your server makes it with your API key and hands only the token to the page. The key never leaves your server.

You rarely call the browser side yourself: the UI SDK asks your page for the token and the editors use it. This page is about the server side: making sessions, what a session can and cannot do, how long it lives, and how to end it.

Preview. The editors you mount with the UI SDK are new. The calls on this page are built and tested, and you can try them now, but small details can still change while this label is on. Tell us what you find at [e-mail].

​

How it works

A session belongs to one managed user. Everything that session reads or makes is that managed user’s: a composition, widget, canvas or file that was made for another of your customers answers 404, exactly as if it did not exist.

​

Make a session

Call this from your server, when the page that holds the editor opens. {id} is Widgetic’s id for the managed user (the UUID the create call gave you), not your own external_id.

cURL

curl -sS -X POST "https://api.widgetic.com/v1/managed-users/$MANAGED_USER_ID/editor-sessions" \
  -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "surfaces": ["creator", "editor", "files"],
    "expires_in_seconds": 3600,
    "allowed_origin": "https://app.example.com"
  }'

Field	Required
surfaces	Yes	What the session may do. One or more of files, editor, creator and workflows. See Surfaces.
expires_in_seconds	No	How long the session lasts: 60 to 14400 (four hours). Default 3600. It cannot be extended: make a new session when it ends.
allowed_origin	No	Bind the session to one web page origin, such as https://app.example.com (no path; http only for localhost). See Bind it to your page.
max_credits	No	The most credits this session may spend on the AI: a whole number from 1 to 1000000, refunds taken off. Leave it out for no limit of its own, unless Widgetic has set a default for your account; send null to ask for none. See A limit for one session.

The answer is 201:

{
  "success": true,
  "data": {
    "token": "wgt_ses_3q2-7wA9vJm5cH1xT0uY8pZkR4nLd6BfGeSoVi2tMqE",
    "sessionId": "9c1d6b7e-5d54-4a0e-8d52-0f3e3c0a6a11",
    "managedUserId": "3f0c9a52-8e0a-4a52-9d52-5d8a1f1b7c10",
    "managedUserExternalId": "your-platform-user-123",
    "surfaces": ["creator", "editor", "files"],
    "allowedOrigin": "https://app.example.com",
    "maxCredits": null,
    "expiresAt": "2026-10-04T14:00:00.000Z",
    "createdAt": "2026-10-04T13:00:00.000Z"
  }
}

• The token is shown once. It starts with wgt_ses_, and the answer is sent with Cache-Control: no-store. Widgetic keeps only a fingerprint of it, so a lost token cannot be read back: make another session.
• sessionId is not a credential. It is only the handle you use to end the session.
• Each call makes a new session. It does not take an Idempotency-Key, because a retry cannot be given the token back.
• A key that is limited to some scopes needs all of partner:write, content:write and generate to make a session, and is refused with 403 API_KEY_SCOPE_MISSING without them (see Limit what a key can do). A key with full access needs nothing more.
• A session is made only while your account is in force and your storage works. A paused account is refused with 403 PARTNER_SUSPENDED, and an account without a storage destination with 409 PARTNER_STORAGE_REQUIRED (see Every session needs your own storage).

​

A server endpoint for your page

Your page needs one endpoint of yours that checks who is signed in, makes a session for that customer and returns the token. The UI SDK calls it again shortly before the token runs out, so the customer is never interrupted.

// Express. WIDGETIC_PARTNER_KEY lives in your server's environment and goes nowhere else.
app.post('/widgetic-session', requireSignedInUser, async (request, response) => {
  const managedUserId = await lookUpWidgeticIdOf(request.user); // the managed user you made for this customer

  const widgetic = await fetch(`https://api.widgetic.com/v1/managed-users/${managedUserId}/editor-sessions`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.WIDGETIC_PARTNER_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      surfaces: ['creator', 'editor', 'files'],
      expires_in_seconds: 3600,
      allowed_origin: 'https://app.example.com',
    }),
  });
  if (!widgetic.ok) return response.status(502).json({ error: 'Could not start a Widgetic session' });

  const { data: session } = await widgetic.json(); // every answer of the API is { success, data }
  response.set('Cache-Control', 'no-store').json({ token: session.token, expiresAt: session.expiresAt });
});

​

Surfaces

A session can do only what its surfaces allow. The surfaces do not imply one another, so ask for every one the editor you mount needs.

Surface	What the session may do	Editor that needs it
files	Upload a file and list the files uploaded for this customer. Every file is filed under this customer and kept in your own storage, and a customer’s file is never stored with Widgetic. See Every session needs your own storage.	File Browser
editor	Open one of this customer’s compositions, read its content, design, embed settings and schemas, and change its name, content, design and embed settings.	Composition editor
creator	Everything the widget creator does for this customer: draw on canvases and save them, make and change widgets, talk to the AI, build, preview and publish a version, and list and make compositions of the widgets it built.	Widget creator
workflows	Everything the Workflows screen does for this customer: list, make (also from a starting point you offer), change, publish, pause, archive, duplicate and delete this customer’s workflows, read their versions and their counts, and pick from this customer’s compositions the ones to chain. A workflow is filed under this customer when it is made.	Workflows

• File Browser: ["files"].
• Composition editor: ["editor", "files"].
• Widget creator: ["creator", "editor", "files"]. The creator saves the composition it is editing (editor) and attaches pictures to its chat (files).
• Workflows: ["workflows"]. The screen uploads no file and opens no composition: it chains compositions by their ids. See Workflows.

The calls behind each surface are listed in the API Reference, under createManagedUserEditorSession.

​

Every session needs your own storage

The files a customer uploads are yours to keep, so an editor session is made only when you have set up your own storage destination: a bucket you own, on any S3-compatible service. Widgetic never keeps a customer’s uploaded file in its own storage. Storage is not optional for a partner, and it does not depend on which surfaces a session asks for.

• No storage, no session. The call that makes the session answers 409 with the code PARTNER_STORAGE_REQUIRED, whatever the surfaces are. When a destination is saved but cannot be used (it is switched off, its credentials cannot be opened, or your account administers two partners that each have one) it answers 503 with STORAGE_DESTINATION_UNAVAILABLE. No session is made, so you hear about it on your server and never from a customer’s browser.
• There is no fallback. If you remove your storage after a session was made, that customer’s uploads are refused until you save a destination again. They are never written to Widgetic’s storage, and they never count against your storage allowance.
• The customer is told one plain sentence: “This is not available right now. Please try again later.” It names neither your storage nor a limit, because it is your setup and not theirs.
• It covers your customers’ uploads, and yours. What a session makes for itself, such as a widget’s code and its previews, stays with Widgetic. The uploads you send with your own key are kept in your storage too: without a destination they are refused with the same 409, and never stored with Widgetic instead.
• An account that is not activated yet cannot make a session at all (PARTNER_INACTIVE), and activation needs a storage destination that works. See Account Status.

​

What a session never does

Everything outside its surfaces is refused with 403 and the code EDITOR_SESSION_ROUTE_NOT_ALLOWED. In particular a session cannot:

• read or change your account, your keys, your contract, your invoices or your credits;
• make more sessions, or list or end sessions;
• see another of your customers’ compositions, widgets, canvases, conversations, files or workflows (those answer 404);
• delete a composition (create it yourself with your key, then open the editor on it);
• make a widget public: what a customer builds stays private to your account (publishing a version of the widget is allowed while your partner agreement is in force, whatever plan your account is on, and it does not make it public);
• file anything under a project or an organization, or set a field the editors do not set. A body with such a field is refused with 403 and EDITOR_SESSION_FIELD_NOT_ALLOWED.

This is the difference between a session and your API key. Your key reaches everything on your account, whoever it was filed under. A session reaches only its own customer’s content.

​

Content the editors can open

A session reaches only content that was filed under its managed user:

• Compositions: create them on your server with your key and name the customer (managedUserId or managedUserExternalId, see Filing Content Under a Managed User), then mount the composition editor on the composition’s id. A composition you made without naming a customer is not reachable by any session.
• Widgets, canvases and compositions made in the widget creator are filed under the session’s managed user automatically. List them from your server with the same managedUserId filter.
• Files a session uploads are filed under its managed user and listed back only for it.
• Workflows a session makes are filed under its managed user automatically, and a session can chain only that customer’s compositions. A workflow of yours that was made without a customer is not reachable by any session. See Workflows.

​

Bind it to your page

Give allowed_origin the origin of the page that mounts the editor. The session is then refused from any other origin, and from a request that carries no Origin header, so a token copied out of your page is useless anywhere else. It is stored as scheme://host[:port]: https (or http for localhost, 127.0.0.1 and [::1]), no path, query or credentials, and no wildcard.

Leave it out only for a session that is used from a server.

​

Lifetime

• A session lasts from 60 seconds to four hours (expires_in_seconds, default one hour). It cannot be extended.
• A managed user can hold up to 100 live sessions. Another request answers 429 with EDITOR_SESSION_LIMIT_REACHED; end the ones you no longer need.
• Mint a session per page open and per customer, from an endpoint that checks who is signed in. Never give one customer’s token to another.
• Switching the managed user off or deleting it ends all of its sessions.

​

End a session

End one session, or all of a customer’s sessions, for example when they sign out of your platform. Both need your key and take effect on the next request (allow up to 15 seconds for every server of ours to notice).

# One session
curl -sS -X DELETE "https://api.widgetic.com/v1/managed-users/$MANAGED_USER_ID/editor-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY"

# Every live session of the customer
curl -sS -X DELETE "https://api.widgetic.com/v1/managed-users/$MANAGED_USER_ID/editor-sessions" \
  -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY"

The first answers 200 with the session’s id (and 404 EDITOR_SESSION_NOT_FOUND for one that was never yours; ending a session that already ended is fine). The second answers 200 with { "ended": 2 }, the number of sessions it ended, and is fine for a customer who has none.

​

Credits and limits

The AI is paid for by your account, as your own calls are: a generation a customer starts uses the same credit as one you start with your key (see Credits & Billing). A customer’s uploads do not use your account’s storage allowance: they are kept in your own storage (see Every session needs your own storage).

• Each customer has an allowance of their own. What a customer does with the AI is counted per customer, not per account or per session: one busy customer cannot use up the others’ turns, a customer who opens many sessions still has one allowance, and your own calls with your key are counted separately. At the moment a customer can start about 26 generations or builds an hour and about 130 a day. A customer who uses it up is refused with 429, the code COST_LIMIT_EXCEEDED and a Retry-After header, and only that customer is. It also keeps a script in one browser from spending all your credits. Everybody starts with the same allowance, and Widgetic can set it for your account alone: tell us if your customers need more, and see Settings that can differ for your account.
• Your credits and plan are yours. When your account cannot pay, every customer is refused: 402 BILLING_INSUFFICIENT_CREDITS (credits) or 403 AUTHZ_PLAN_RESTRICTION (your plan does not include it). A customer is never told what your account holds: the message is one plain sentence, “This is not available right now. Please try again later.”, with no balance, cost or plan. The same calls made with your key keep the full messages.
• The editors tell your page. The widget creator reports these as a limitReached event, once per code in half a minute, so your page can offer more or tell its own team. See Canvas Embedding.
• Workflows use no credits and have a limit of their own. Making, saving and publishing a workflow is not an AI call, so it takes nothing from your credits and is not counted against a customer’s allowance. A customer can hold up to 50 workflows, archived ones included. See Limits and cost.
• Ordinary rate limiting (RATE_LIMIT_EXCEEDED) counts the address each request comes from, not your account, so your customers do not share it. It is not a limit your page needs to report.
• You can hold one session to a number of credits, and see what each customer spent. See A limit for one session and What each customer spent.

​

A limit for one session

Send max_credits when you make a session, and that session can spend at most that many credits on the AI. Refunds are taken off: a generation that fails gives its credit back to the session as well as to your account.

curl -sS -X POST "https://api.widgetic.com/v1/managed-users/$MANAGED_USER_ID/editor-sessions" \
  -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "surfaces": ["creator", "editor", "files"], "max_credits": 20 }'

• The call that would go past the limit is refused before anything is taken from your account. The answer is 402 with the code EDITOR_SESSION_CREDIT_LIMIT_REACHED. The customer reads the same plain sentence as for any other limit, never the limit or what was spent. The widget creator tells your page with a limitReached event whose code is this one, so you can tell it from an account that is out of credits (BILLING_INSUFFICIENT_CREDITS).
• The limit belongs to the session. A new session starts again from zero. For a cap on what a customer may spend in a day or a month, read their usage on your server and stop making sessions at your own number.
• Only calls that take credits count. Building a widget takes none, so it is never counted or held back by max_credits.
• A limit that cannot be checked does not let the call through. If Widgetic cannot read what the session has spent, the call is refused with 503 and the customer can try again in a moment.

​

Settings that can differ for your account

Editor sessions behave the same for every partner by default. If your account needs something different, Widgetic can set any of these three for your account alone, and nothing else about your account changes:

Setting	What it does	What you see
Sessions switched off	Editor sessions are not made for your account. It can only narrow what everybody gets: it never switches on what Widgetic has switched off for all.	A new session is refused with 403 EDITOR_SESSIONS_DISABLED_FOR_PARTNER, and a customer’s open session is refused the same way
A larger allowance	What one operation of your customers costs against their own allowance is smaller, so each customer can do more before COST_LIMIT_EXCEEDED	Customers are refused later. Nothing to change in your calls
A default limit for new sessions	The max_credits a session gets when your request does not name one. A request that names its own limit, or null for none, keeps it	A session that you made without max_credits can still end with EDITOR_SESSION_CREDIT_LIMIT_REACHED

A change reaches every server within about a quarter of a minute. Ask [e-mail] when you need one.

​

What each customer spent

Your account pays for the AI, so your credit ledger does not say which of your customers used what. Widgetic notes every call that a customer’s session paid for, and adds the notes up for one customer over a period:

cURL

curl -sS "https://api.widgetic.com/v1/managed-users/$MANAGED_USER_ID/usage?startDate=2026-10-01&endDate=2026-11-01" \
  -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY"

{
  "success": true,
  "data": {
    "managedUserId": "3f0c9a52-8e0a-4a52-9d52-5d8a1f1b7c10",
    "managedUserExternalId": "your-platform-user-123",
    "from": "2026-10-01T00:00:00.000Z",
    "to": "2026-11-01T00:00:00.000Z",
    "totals": { "calls": 41, "credits": 41, "refundedCalls": 3, "refundedCredits": 3 },
    "operations": [
      { "operation": "agent.code.generate", "calls": 41, "credits": 41, "refundedCalls": 3, "refundedCredits": 3 }
    ]
  }
}

• calls and credits are what the customer’s sessions spent and kept. A call that failed and was refunded is in refundedCalls and refundedCredits instead, so it never counts against the customer.
• The period runs from startDate (included) to endDate (not included). Give neither and it is the 30 days before now; it can be 366 days at most. A date without a time is midnight UTC, so for all of October give 2026-10-01 and 2026-11-01. A date-time must say its offset (2026-10-01T08:00:00Z).
• Only what a customer’s sessions spent is counted, from the day Widgetic first recorded it. What you spend with your own key is not in it, and neither is anything from before.
• It answers for your managed users only. One that is not yours answers 404 with MANAGED_USER_NOT_FOUND, exactly like one that does not exist. A date that is not a date, a startDate that is not before endDate, or a period over 366 days answers 400.

​

Browsers

A browser may call the API with a session token from any origin. The API answers the preflight request for the calls a session may make, echoes the origin on the real call, and never sends Access-Control-Allow-Credentials: a session does not use cookies, only the Authorization header. It exposes the Retry-After, X-Idempotency-Cached and X-Correlation-Id headers to the page. Quote the X-Correlation-Id to Widgetic’s support when you report a problem.

If your page sends a Content-Security-Policy, see UI Components for what the editors need.

​

Errors

The browser side of a session answers with these. The editors handle them for you and tell your page (error event with sessionEnded: true when the token cannot be used again).

Status	Code	Meaning	What to do
401	EDITOR_SESSION_INVALID	The token is not one of ours	Mint a new session
401	EDITOR_SESSION_EXPIRED	The session ran out	Mint a new session
401	EDITOR_SESSION_REVOKED	You ended it, or the customer was switched off	Mint a new session if the customer should continue
401	EDITOR_SESSION_USER_UNAVAILABLE	The managed user no longer exists or is switched off	Do not mint another until the customer is back
402	EDITOR_SESSION_CREDIT_LIMIT_REACHED	The session has spent the max_credits you gave it	Mint a new session if the customer may spend more
403	PARTNER_SUSPENDED, PARTNER_INACTIVE	Your partner account is paused, or not activated yet. The customer reads only: “This service is not available right now. Please contact the website that sent you here.”	Nothing for the customer to do. See Account Status
403	EDITOR_SESSIONS_DISABLED_FOR_PARTNER	Widgetic switched editor sessions off for your account alone. The customer reads: “Editor sessions are not available for this account.”	Write to Widgetic
403	EDITOR_SESSION_ORIGIN_NOT_ALLOWED	The session is bound to another page	Mint it with this page’s allowed_origin
403	EDITOR_SESSION_ROUTE_NOT_ALLOWED	A session cannot make this call	Not a session’s job: do it from your server
403	EDITOR_SESSION_FIELD_NOT_ALLOWED	The request sets a field a session may not set	Remove the field
404	RESOURCE_…_NOT_FOUND, such as RESOURCE_WIDGET_NOT_FOUND or RESOURCE_WORKFLOW_NOT_FOUND	The item is not this customer’s, does not exist, or is not even an id (for a workflow, an id that is not a UUID answers 403 EDITOR_SESSION_ROUTE_NOT_ALLOWED instead)	File it under the customer, or check the id
409	PARTNER_STORAGE_REQUIRED	The customer uploaded a file and you have no storage destination	Set up your own storage (see Every session needs your own storage). The customer reads only the plain sentence
503	EDITOR_SESSIONS_DISABLED	Editor sessions are switched off for the moment	Try again later

Making a session can also answer: 400 (a surface that does not exist, expires_in_seconds or max_credits out of range, or allowed_origin that is not an origin), 403 (the caller is not a partner), 404 MANAGED_USER_NOT_FOUND, 409 MANAGED_USER_INACTIVE (switched off managed users get no sessions), 409 PARTNER_STORAGE_REQUIRED (the files surface, and no storage destination of your own), 429 EDITOR_SESSION_LIMIT_REACHED, 503 STORAGE_DESTINATION_UNAVAILABLE (the storage you set up cannot be used) and 503 EDITOR_SESSIONS_DISABLED.

​

Security checklist

1. Keep the key on your server

   Make sessions only from your server. Never send your wgt_prt_ key to a browser: it carries the access of your whole account. Use an editor session instead.

2. Check who is signed in

   Your endpoint must make the session for the customer who is signed in, and for nobody else.

3. Bind it to your page

   Send allowed_origin so that a copied token is useless on any other web page.

4. Keep tokens out of logs, storage and URLs

   Hold the token in memory. The UI SDK does.

5. End sessions when customers leave

   Call DELETE /managed-users/{id}/editor-sessions when a customer signs out, and switch the managed user off when their plan on your platform ends.

​

Next Steps

UI Components

Mount the editors in your page with the UI SDK

Canvas Embedding

The widget creator and the composition editor

Workflows

Let a customer chain their compositions into a path

Managed Users

File your customers’ content under them

Credits & Billing

How the AI is paid for