> ## Documentation Index > Fetch the complete documentation index at: https://widgetic.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 `. 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`. ## OpenAPI ````yaml /openapi/widgetic-api-public.json post /managed-users/{id}/editor-sessions openapi: 3.0.0 info: title: Widgetic API Gateway version: 1.0.0 description: API documentation for the Widgetic API Gateway license: name: Widgetic Integration License url: https://docs.widgetic.com/resources/license servers: - url: https://api.widgetic.com/v1 description: Production server variables: env: default: production description: Environment apiUrl: default: https://api.widgetic.com description: API URL apiVersion: default: /v1 description: API Version path prefix security: [] tags: [] paths: /managed-users/{id}/editor-sessions: post: tags: - Managed Users summary: Create an editor session for a managed user description: > 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 `. 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`. operationId: createManagedUserEditorSession parameters: - in: path name: id required: true schema: type: string format: uuid description: The managed user the session is for (Widgetic's id for the user) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NewEditorSession' responses: '201': description: The session, with its token (shown once) content: application/json: schema: $ref: '#/components/schemas/EditorSessionResponse' '400': description: >- A surface is not one that exists, `expiresInSeconds` or `maxCredits` is out of range, or `allowedOrigin` is not an origin content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Forbidden - the caller is not a partner, or Widgetic has switched editor sessions off for your account (`EDITOR_SESSIONS_DISABLED_FOR_PARTNER`) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- No managed user with this id on your account (`MANAGED_USER_NOT_FOUND`). Another partner's managed user answers 404 as well. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- The managed user is switched off, so no session can be made for it (`MANAGED_USER_INACTIVE`); or you have not set a storage destination (`PARTNER_STORAGE_REQUIRED`) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: >- The managed user already has the most live sessions allowed (`EDITOR_SESSION_LIMIT_REACHED`) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Editor sessions are switched off for the moment (`EDITOR_SESSIONS_DISABLED`), or your storage destination cannot be used (`STORAGE_DESTINATION_UNAVAILABLE`). Try again later. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - apiKeyAuth: [] x-code-samples: - lang: TypeScript label: TypeScript SDK source: > 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. components: schemas: NewEditorSession: type: object required: - surfaces properties: surfaces: type: array minItems: 1 items: type: string enum: - files - editor - creator - workflows description: > 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. example: - files - editor expiresInSeconds: type: integer minimum: 60 maximum: 14400 default: 3600 description: >- How long the session lasts, in seconds. It cannot be extended; make a new session when it ends. example: 3600 allowedOrigin: type: string nullable: true description: > 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: type: integer minimum: 1 maximum: 1000000 description: > 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. example: 20 example: surfaces: - files - editor expiresInSeconds: 3600 allowedOrigin: https://app.example.com maxCredits: 20 EditorSessionResponse: type: object required: - success - data properties: success: type: boolean description: Always `true` on a success. example: true data: $ref: '#/components/schemas/EditorSession' meta: $ref: '#/components/schemas/ResponseMeta' ErrorResponse: type: object required: - success - message - error additionalProperties: true properties: success: type: boolean description: Always `false` on a failure. example: false message: type: string description: The same text as `error.message`, for a caller that reads one line. error: $ref: '#/components/schemas/ErrorDetail' EditorSession: type: object description: > 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. required: - token - sessionId - managedUserId - managedUserExternalId - surfaces - expiresAt - createdAt properties: token: type: string description: > The credential the browser sends as `Authorization: Bearer `. It starts with `wgt_ses_`. It works only for the calls of the session's surfaces, only for this managed user's content, and only until `expiresAt`. example: wgt_ses_3q2-7wA9vJm5cH1xT0uY8pZkR4nLd6BfGeSoVi2tMqE sessionId: type: string format: uuid description: >- Identifies the session, so you can end it (`revokeManagedUserEditorSession`). It is not a credential. managedUserId: type: string format: uuid managedUserExternalId: type: string description: Your own identifier for the managed user surfaces: type: array items: type: string enum: - files - editor - creator - workflows allowedOrigin: type: string nullable: true description: >- The web page origin the session is bound to, or null when it is not bound maxCredits: type: integer nullable: true description: >- The most credits the session may spend on Widgetic's AI (`max_credits`), or null when it has no limit of its own expiresAt: type: string format: date-time createdAt: type: string format: date-time 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' ResponseMeta: type: object description: >- 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. additionalProperties: true properties: page: type: integer description: The page that was read, counting from 1. example: 1 size: type: integer description: How many items one page holds. example: 20 total: type: integer description: How many items the whole list has. example: 135 limit: type: integer description: The same as `size`. example: 20 offset: type: integer description: How many items come before this page. example: 0 hasNextPage: type: boolean example: true hasPreviousPage: type: boolean example: false nextCursor: type: string nullable: true description: >- Pass this as `cursor` to read the next page of a list that is read by cursor. `null` on the last page. warnings: type: array items: type: string description: >- Things the call did not do, though it succeeded (for example a table that could not be created just now). ErrorDetail: type: object required: - code - message - timestamp properties: code: type: string description: Machine-readable error code. example: RESOURCE_NOT_FOUND message: type: string description: Human-readable explanation. example: Composition not found param: type: string description: The field that caused the error, when one did. example: name docUrl: type: string description: Where this error is explained. suggestedAction: type: string description: What to do about it. retryAfter: type: integer description: >- Seconds to wait before trying again (rate limits). The same number is in the `Retry-After` header. example: 60 details: type: object additionalProperties: true description: >- More about the error: the fields that failed, a limit that was reached. correlationId: type: string description: Quote this when you ask support about the call. example: req_123e4567-e89b-12d3-a456-426614174000 timestamp: type: string format: date-time example: '2026-10-15T10:00:00.000Z' securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.