Create an editor session for a managed user

Makes a short-lived credential that lets the browser of ONE of your managed users use Widgetic’s editor pieces, such as the File Browser and the composition editor, without your API key ever reaching that browser. Call this from your server when the page that hosts the editor opens, and hand the token in the answer to that page.

The token is shown once. It starts with wgt_ses_ and the browser sends it as Authorization: Bearer <token>. It can do only what the surfaces you name allow, and only for this managed user:

• files: upload a file (uploadFile) and list the files uploaded for this user (listUploads). Every file is filed for this user and stored in your own storage destination, never in Widgetic’s: a file a customer uploads is yours to keep, and takes none of your storage allowance. Partner storage is not optional, so no session, whatever its surfaces, can be made until you have set a destination (setPartnerStorageDestination); until then it is refused with 409 and PARTNER_STORAGE_REQUIRED, and when the destination cannot be used with 503 and STORAGE_DESTINATION_UNAVAILABLE. A destination you remove after the session was made stops its uploads too (the same 409; the browser is only told that the feature is not available right now). To keep a customer from uploading, leave files out of the session and hand the editors your own media library instead (mediaLibrary).
• editor: edit one of this user’s compositions: read it (getCompositionById, its content, design, embed settings and schemas), check a content change (validateCompositionContent), and change its name, content, design and embed settings (updateComposition, setDynamicContent). For a widget that answers visitors’ questions from documents (the ai-answers adapter), it also lists those documents, adds one as text or as a file (a text file or a picture; a PDF once PDFs are read), and removes one (getAiAnswersKnowledge, addAiAnswersKnowledgeDocument, addAiAnswersKnowledgeFile, removeAiAnswersKnowledgeDocument); adding costs no credits, and is limited for each of your users separately. It can reach only compositions you created for this managed user (tag them with managedUserId when you create them); any other composition, including another of your users’, answers 404.
• creator: use Widgetic’s widget creator for this user, including its AI. Draw on canvases and save them (getAllCanvases, getCanvas, createCanvas, updateCanvas, previewDeleteCanvas, deleteCanvas); make, change, copy and delete the widgets on them (createWidget, getWidgets, getWidgetsBatch, updateWidget, uploadWidgetThumbnail, duplicateWidget, deleteWidget); list and make the compositions of a widget it built (getAllCompositions, createComposition), which is how it shows the widget with sample values; keep the conversation of each widget (getConversationsByWidgetId, createConversationForWidget, updateConversation, getMessages, createMessage, updateMessage, restoreCheckpoint); and read a widget’s schemas and give it its repository (getWidgetContentSchema, getWidgetDesignSchema, updateWidgetRepository). The AI that builds a widget is part of it: list the models (listLlmModels), open the widget’s repository (createRepository, getRepository), start a generation and follow or cancel it (generateCode, streamOperationUpdates, getOperation, cancelOperation), build and preview the result (getWidgetRepositoryHead, buildWidgetFromRepo, previewWidgetVersion), publish a version of the widget and move between its versions (publishBuiltWidget, getWidgetPublishHistory, setWidgetPublishHistoryLive, renameWidgetPublishHistoryTitle), and turn a stroke or a sentence into a decision (recognizeShape, resolveDesignProperty). It can also offer the customer your presets as starting points: read them and ask for a copy for this customer (listMyPresets, copyMyPreset; you choose the presets with setPartnerPreset). What the session makes is filed for this managed user, and the lists it reads hold only this user’s canvases, widgets and compositions. It can reach only canvases, widgets, compositions, repositories, uploaded files and operations made for this managed user (tag the canvases and widgets you create with managedUserId); any other canvas, widget, composition, conversation, message, repository, file or operation, including another of your users’, answers 404. The creator also saves the composition it is editing (updateComposition, from the editor surface) and attaches pictures to its chat (uploadFile, from the files surface), and the surfaces do not imply one another: to open the whole creator for a user, ask for creator, editor and files together. A generation or a build one user starts can be followed and cancelled by that user and by you, never by another of your users. The AI is paid for by your account, as your own calls are: its credits and allowances are yours. A session cannot make a widget public (publishing a version does not), file one under a project or an organization, or set anything the creator does not set: a body with another field is refused with 403 and EDITOR_SESSION_FIELD_NOT_ALLOWED.
• workflows: use Widgetic’s Workflows editor for this user. List their workflows and the compositions a workflow of theirs can chain (listWorkspaceWorkflows, listWorkspaceWorkflowCompositionOptions); list the starting points you offer them and make a workflow from one, which gives the user their own copy of every widget it chains, a composition of their own on each copy, and a draft (listWorkspaceWorkflowPresets, createWorkspaceWorkflowFromPreset; you offer them with setPartnerWorkflowPreset); make, open, change and delete one (createWorkspaceWorkflow, getWorkspaceWorkflow, saveWorkspaceWorkflow, deleteWorkspaceWorkflow) and copy it (duplicateWorkspaceWorkflow); publish it or discard the changes of its draft (publishWorkspaceWorkflow, discardWorkspaceWorkflowChanges); read and restore its versions (listWorkspaceWorkflowVersions, getWorkspaceWorkflowVersion, restoreWorkspaceWorkflowVersion); pause, resume, archive and unarchive it (pauseWorkspaceWorkflow, resumeWorkspaceWorkflow, archiveWorkspaceWorkflow, unarchiveWorkspaceWorkflow); and read its counts (getWorkspaceWorkflowStats). The workspace in each path is personal: a session has no other, and a path that names an organization is refused. What the session makes is filed for this managed user (managedUserId), the lists hold only this user’s workflows, and it can reach only workflows made for this managed user; any other workflow, including one of yours or of another of your users, answers 404. A workflow can chain only the compositions you made for this managed user (tag them with managedUserId): one that belongs to anybody else is not available, and publishing a workflow that uses it is refused. A customer can have at most 50 workflows, and what a customer’s session reads never says who published a version. A session cannot set who a workflow belongs to or which workspace it is in: a body with another field is refused with 403 and EDITOR_SESSION_FIELD_NOT_ALLOWED.

Everything else is refused with 403 and EDITOR_SESSION_ROUTE_NOT_ALLOWED: a session cannot read your account, make more sessions, change your presets or delete a composition, and a session without the creator surface cannot create or list compositions. Create the composition yourself with your API key, then open the editor on it.

A session ends at expiresAt (at most four hours), when you end it (revokeManagedUserEditorSession), or when the managed user is switched off or deleted. A managed user can have at most 100 live sessions at once (429 EDITOR_SESSION_LIMIT_REACHED). A session that is bound to a web page (allowedOrigin) is refused from any other origin.

The AI the session runs is paid for with your credits. Set maxCredits to hold the session to a number of them: once its generations have taken that many (a generation that fails is refunded and does not count), the next one is refused with 402 and EDITOR_SESSION_CREDIT_LIMIT_REACHED, and the browser is told only that the feature is not available right now. Without it, the limit Widgetic has set for your account applies when it has set one (the same limit for every session you make, and maxCredits: null asks for none), and otherwise the credits of your account are the only ceiling. What each of your users’ sessions has spent is in getManagedUserUsage.

Each call makes a new session. It does not take an Idempotency-Key: the answer holds the token, and the token is never stored where a retry could read it back. The answer is sent with Cache-Control: no-store.

POST /managed-users/{id}/editor-sessions

TypeScript SDK

TypeScript

import { Configuration, ManagedUsersApi } from '@widgetic/api-sdk-ts';

const managedUsersApi = new ManagedUsersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));

// On your server, when the page that hosts the editor opens for one of your users:
const session = await managedUsersApi.createManagedUserEditorSession({
  id: managedUserId,
  newEditorSession: {
    surfaces: ['files', 'editor'],
    expiresInSeconds: 3600,
    allowedOrigin: 'https://app.example.com',
    maxCredits: 20
  }
});

// Send session.token to that user's browser, and nothing else of yours.

201

{
  "success": true,
  "data": {
    "token": "wgt_ses_3q2-7wA9vJm5cH1xT0uY8pZkR4nLd6BfGeSoVi2tMqE",
    "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "managedUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "managedUserExternalId": "Example managedUserExternalId",
    "surfaces": [],
    "allowedOrigin": "Example allowedOrigin",
    "maxCredits": 42,
    "expiresAt": "2026-01-15T09:30:00.000Z",
    "createdAt": "2026-01-15T09:30:00.000Z"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id · string<uuid> · required

The managed user the session is for (Widgetic's id for the user)

Body

application/json

surfaces · enum<string>[] · required

The pieces of Widgetic's editor the session may drive. files is the media library (the File Browser: upload a file, list the files uploaded for this user); what a user uploads is kept in your own storage destination. Partner storage is not optional: a session of any surface can be made only once you have set a destination up (setPartnerStorageDestination), and is refused with 409 PARTNER_STORAGE_REQUIRED until then. editor is editing one of this user's compositions: read it, change its name, content, design and embed settings, read its schemas, and ask where to show it (getCompositionPreview: the widget's published page). creator is Widgetic's widget creator, with its drawing canvas and its AI: this user's canvases, the widgets on them and the conversation of each widget, the generation, build and publish calls that make a widget, and the compositions of those widgets (list, make). The surfaces do not imply one another: the whole creator also saves a composition (editor) and attaches pictures to its chat (files), so ask for ["creator", "editor", "files"]. workflows is the Workflows editor: this user's own workflows (list, make, make from one of your starting points, draw, publish, pause, resume, archive, delete, the version history and the counts) under /workspaces/personal/workflows, and the compositions made for this user, which are the only ones a workflow of theirs can chain. A workflow is filed under the user it was made for (managedUserId), and the session reaches nothing of another user's, nor of yours.

Minimum array length: 1

Available options: files, editor, creator, workflows

Example:

["files", "editor"]

expiresInSeconds · integer · default: 3600

How long the session lasts, in seconds. It cannot be extended; make a new session when it ends.

Required range: 60 <= x <= 14400

Example:

3600

allowedOrigin · string | null

Bind the session to one web page origin, such as https://app.example.com (no path; http is accepted only for localhost). The session is then refused from any other origin, and from a request that carries no Origin header. Leave it out for a session that can be used from anywhere, which is what a server-side caller needs.

Example:

"https://app.example.com"

maxCredits · integer

The most credits this session may spend on Widgetic's AI, one credit being one generation. Once the operations it ran have taken that many, the next one is refused (402, EDITOR_SESSION_CREDIT_LIMIT_REACHED) and the browser is only told that the feature is not available right now. A generation that fails is refunded and does not count. Leave it out to get the limit Widgetic has set for your account, if it has set one (it sets none unless you ask), and otherwise no limit of its own, which leaves the credits of your account as the only ceiling. Send null to ask for no limit of its own even when a default is set.

Required range: 1 <= x <= 1000000

Example:

20

Response

201

application/json

The session, with its token (shown once)

success · boolean · required

Always true on a success.

Example:

true

data · object · required

An editor session you have just made. token is shown once and cannot be read again: hand it to the browser of this one user and keep it out of logs and storage.

Show child attributes

Example:

{
  "token": "wgt_ses_3q2-7wA9vJm5cH1xT0uY8pZkR4nLd6BfGeSoVi2tMqE",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "managedUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "managedUserExternalId": "Example managedUserExternalId",
  "surfaces": [],
  "allowedOrigin": "Example allowedOrigin",
  "maxCredits": 42,
  "expiresAt": "2026-01-15T09:30:00.000Z",
  "createdAt": "2026-01-15T09:30:00.000Z"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes