Define a robot token with Blueprints

Blueprints allow you to create robot tokens alongside other resources for use in the blueprint.

Robot tokens let your code make authenticated requests to Sanity. When created with Blueprints, they’re often used to provide explicit access in Functions.

In this guide, you’ll define a robot token resource with Blueprints and deploy the blueprint to Sanity.

Prerequisites:

• The latest version of sanity CLI is recommended to interact with Blueprints. You can always run the latest CLI commands with npx sanity@latest.
• An existing project and a role with permission to edit robot tokens (requires the sanity-project-tokens permission).
• Robot token support was first introduced in @sanity/blueprints v0.11.0. We recommend using the latest version of the library.

To initialize a blueprint in the current directory, run the command below. Replace the project ID with your own. Skip to the next section if you already have a blueprint set up.

npx sanity@latest blueprints init . --type ts --project-id <project-id> --stack-name production

pnpm dlx sanity@latest blueprints init . --type ts --project-id <project-id> --stack-name production

yarn dlx sanity@latest blueprints init . --type ts --project-id <project-id> --stack-name production

bunx sanity@latest blueprints init . --type ts --project-id <project-id> --stack-name production

Use the defineRobotToken helper to define a robot token resource.

import { defineBlueprint, defineRobotToken } from "@sanity/blueprints"

export default defineBlueprint({
  resources: [
    defineRobotToken({
      name: 'editor-robot',
      memberships: [
        {
          resourceType: 'project',
          resourceId: 'your-project-id',
          roleNames: ['editor']
        }
      ]
    })
  ],
})

A full list of available configuration options is available in the reference documentation.

Reference the token in your function definition to make it available to your custom functions. This makes the function use the custom-scoped robot token instead of the default token with broad read/write permissions.

import {defineBlueprint, defineRobotToken, defineDocumentFunction} from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineRobotToken({
      name: 'editor-robot',
      memberships: [
        {
          resourceType: 'project',
          resourceId: 'your-project-id',
          roleNames: ['editor']
        }
      ]
    }),
    defineDocumentFunction({
      name: 'my-function',
      // Replace `editor-robot` with your token name
      robotToken: '$.resources.editor-robot.token',
      // ... rest of config
    }),
  ]
})

Next, deploy the blueprint.

npx sanity blueprints deploy

pnpm dlx sanity blueprints deploy

yarn dlx sanity blueprints deploy

bunx sanity blueprints deploy

Once the deployment finishes, the robot token is active.

If you need to make changes, update the blueprint file (sanity.blueprint.ts) and run the deploy command again.

To remove a resources created with a blueprint, you need to either:

• Remove the definition from the blueprint, and run the deploy command again.
• Destroy the blueprint with the destroy command.

Destroy will “undeploy” the blueprint and remove the stack, leaving only your local files.

When you run blueprints destroy, it's as if you never used blueprints init during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:

npx sanity blueprints init

pnpm dlx sanity blueprints init

yarn dlx sanity blueprints init

bunx sanity blueprints init

This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.