SDK scopes

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

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

{
  "metadata": {
    "name": "My App",
    "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:create: upload custom fonts via kittl.font.createFont.
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:create`	`kittl.font.createFont`
`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:

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

If you upload images, include uploads:create:

{
  "metadata": {
    "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​