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).
• 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 exact scope required for each SDK method. Methods not listed here (e.g. kittl.context.get) are 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.design.canvas.getExport	Export to blob
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.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
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
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.