Version: 0.0.9

SDK scopes

Scopes define which SDK operations your app is allowed to call. config.scopes is mandatory in manifest.json.

Declare scopes in manifest.json under config.scopes. This is a partial snippet showing only the relevant part (not a full manifest):

{
  "config": {
    "scopes": ["design:state:read", "design:state:write"]
  }
}

For a complete manifest.json example, see App manifest.

Supported scopes

These are the currently supported scopes:

design:state:read: read design and editor state via SDK APIs.
design:state:write: update design state (for example add, remove, and update objects).
export:bypass: export directly with kittl.export.bypassExportDialog() without opening the export modal. This scope also requires developer organization approval.
uploads:create: upload files with kittl.upload.image.upload({ blob }); apps can then use their own uploaded files.
uploads:global:read: allows an app to read all uploads available in the current workspace (not limited to the current user's uploads).
ai:credit:spend: spend AI credits via kittl.ai.spendCredits.
fonts:read: read fonts created by the extension.
fonts:write: create or modify fonts created by the extension via kittl.data.fonts.
fonts:read:global: read all custom fonts available to the user.
fonts:write:global: modify all custom fonts available to the user.
data:mockups:read: browse and search the mockup catalog via kittl.data.mockups.
workspace:state:read: reserved for workspace state reads.
workspace:state:write: reserved for workspace state writes.

Scope to SDK API mapping

The table below shows the scopes for the documented SDK methods. kittl.context.get is exempt and always allowed.

`design:state:read`

Method	Description
`kittl.design.canvas.getPreviewImage`	Get a board preview image
`kittl.design.canvas.getScreenshot`	Capture canvas screenshot
`kittl.export.showExportModal`	Open the host export modal for selected targets
`kittl.design.object.getObject`	Get object by ID
`kittl.design.object.getAllByFilter`	Query objects by predicate
`kittl.state.viewport.get`	Get viewport state
`kittl.state.viewport.set`	see `design:state:write`
`kittl.state.getSelectedObjectsIds`	Get selected object IDs
`kittl.state.getSelectedLayersIds`	Get selected layer IDs
`kittl.state.getSelectedArtboardIds`	Get selected artboard IDs
`kittl.state.getCanvasMode`	Get canvas mode
`kittl.state.getActiveTool`	Get active tool
`kittl.state.getHighlightedObjectId`	Get highlighted object ID

`design:state:write`

Method	Description
`kittl.design.board.createStandardBoard`	Create artboard
`kittl.design.board.cloneArtboard`	Clone artboard
`kittl.design.board.updateArtboard`	Update artboard
`kittl.design.text.addText`	Add text
`kittl.design.text.updateText`	Update text
`kittl.design.text.updateRenderPlugin`	Update text render plugin
`kittl.design.text.updateDecorationPlugin`	Update text decoration plugin
`kittl.design.shape.createPredefinedShape`	Create predefined shape
`kittl.design.shape.createBasicShape`	Create basic shape from SVG
`kittl.design.shape.updateShape`	Update shape
`kittl.design.shape.convertShapeToMask`	Convert shape to mask
`kittl.design.image.addImage`	Add image
`kittl.design.image.updateImage`	Update image
`kittl.design.video.addVideo`	Add video
`kittl.design.video.updateVideo`	Update video
`kittl.design.video.updatePlaylistItem`	Update video playlist item
`kittl.design.video.removePlaylistItem`	Remove video playlist item
`kittl.design.object.removeObject`	Remove object
`kittl.design.object.setLockedState`	Lock/unlock object
`kittl.design.object.setHiddenState`	Show/hide object
`kittl.design.object.rotateObject`	Rotate object
`kittl.design.object.rename`	Rename object
`kittl.design.config.setConfig`	Update design config
`kittl.design.loadingCard.createLoadingCard`	Create loading card
`kittl.design.loadingCard.updateLoadingCard`	Update loading card
`kittl.design.mockupboard.addMockupBoard`	Add mockup board
`kittl.design.mockupboard.addMockupDesignObject`	Add mockup design object
`kittl.design.mockupboard.updateMockupBoard`	Update mockup board
`kittl.state.setSelectedObjectsIds`	Set selected objects
`kittl.state.setSelectedLayersIds`	Set selected layers
`kittl.state.setSelectedArtboardIds`	Set selected artboards
`kittl.state.setCanvasMode`	Set canvas mode
`kittl.state.setCustomCanvasMode`	Set an extension-defined canvas mode with JSON state
`kittl.state.setActiveTool`	Set active tool
`kittl.state.setHighlightedObjectId`	Set highlighted object
`kittl.state.setMany`	Batch-update state fields
`kittl.state.viewport.set`	Set viewport state

Other scopes

Scope	Method
`export:bypass` (plus developer organization approval)	`kittl.export.bypassExportDialog`
`ai:credit:spend`	`kittl.ai.spendCredits`
`ai:credit:spend`	`kittl.ai.startGeneration`
`ai:credit:spend`	`kittl.ai.registerHandler`
`fonts:read:global`	`kittl.data.fonts.listUserFonts`
`fonts:read` or `fonts:read:global`	`kittl.data.fonts.listExtensionFonts`
`fonts:read` or `fonts:read:global`	`kittl.data.fonts.get`
`fonts:read` or `fonts:read:global`	`kittl.data.fonts.find`
`fonts:write`	`kittl.data.fonts.create`
`fonts:write` or `fonts:write:global`	`kittl.data.fonts.update`
`fonts:write` or `fonts:write:global`	`kittl.data.fonts.delete`
`fonts:write` or `fonts:write:global`	`kittl.data.fonts.destroy`
`fonts:write` or `fonts:write:global`	`kittl.data.fonts.addStyle`
`fonts:write` or `fonts:write:global`	`kittl.data.fonts.updateStyle`
`fonts:write` or `fonts:write:global`	`kittl.data.fonts.deleteStyle`
`data:mockups:read`	`kittl.data.mockups.get`
`data:mockups:read`	`kittl.data.mockups.getOverview`
`data:mockups:read`	`kittl.data.mockups.getGroup`
`data:mockups:read`	`kittl.data.mockups.search`
`data:mockups:read`	`kittl.data.mockups.getSuggestions`
`uploads:create`	`kittl.upload.image.upload({ blob })`

Exempt methods

These methods are always allowed regardless of declared scopes:

kittl.context.get — host context (drag-and-drop offset)
kittl.dragAndDrop.startDragImageEvent / dropImage — client-side drag-and-drop helpers
kittl.stateless.send / subscribe / unsubscribe — inter-extension messaging
kittl.onReady — SDK readiness callback

Choosing scopes

If your app both reads and mutates design/editor state, declare both:

{
  "config": {
    "scopes": ["design:state:read", "design:state:write"]
  }
}

If you upload images, include uploads:create:

{
  "config": {
    "scopes": [
      "design:state:read",
      "design:state:write",
      "uploads:create"
    ]
  }
}

Error behavior

If your app calls a method without required scope, the call fails with an SDK error result (isOk: false) and a permission-denied style message.

To avoid runtime failures, request the smallest scope set that still covers all methods your app calls.

Supported scopes​

Scope to SDK API mapping​

design:state:read​

design:state:write​

Other scopes​

Exempt methods​

Choosing scopes​

Error behavior​