Use robot tokens with Functions

Learn how to authenticate Sanity Functions using robot tokens defined with Blueprints.

Robot tokens enable your functions to authenticate API calls to Sanity without managing credentials manually. You can choose to create a token yourself as shown in this guide, or one will be created when you deploy your blueprint.

In this guide, you'll define a robot token with Blueprints, assign it to a function, and deploy the blueprint.

Prerequisites:

• Functions run on Node.js v24.x by default.
• The latest version of the Sanity CLI is recommended. Run commands with npx sanity@latest.
• A Sanity project ID where you have permission to create robots and deploy functions. Creating robot tokens requires the sanity-project-tokens permission.
• @sanity/blueprints v0.12.0 or later, which introduced defineRobotToken.

Robots are service accounts that provide authentication tokens for automated access. When you define a token in a blueprint:

• The token is created during deployment with the specified roles. Sanity generates and manages the token value.
• Functions reference the token with $.resources.ROBOT_NAME.token, where ROBOT_NAME is the name of your robot token resource.
• The token is injected into your function to be used at function runtime.

These are similar to robot tokens defined in your project or organization settings, but they are managed by the blueprint instead.

Use the defineRobotToken helper to define a token in your blueprint configuration. Replace <your-project-id> with your project ID.

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

export default defineBlueprint({
  resources: [
    defineRobotToken({
      name: 'my-robot',
      label: 'My Robot',
      memberships: [
        {
          resourceType: 'project',
          resourceId: 'YOUR_PROJECT_ID',
          roleNames: ['editor'],
        },
      ],
    })
  ]
})

You can find a list of available roles for your project with the Access API, or in your project's settings at sanity.io/manage.

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

Reference the robot token in your function definition:

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

export default defineBlueprint({
  resources: [
    defineRobotToken({
      name: 'my-robot',
      label: 'My Robot',
      memberships: [
        {
          resourceType: 'project',
          resourceId: 'YOUR_PROJECT_ID',
          roleNames: ['editor'],
        },
      ],
    }),
    defineDocumentFunction({
      name: 'my-function',
      robotToken: '$.resources.my-robot.token',
      // ... rest of config
    }),
  ]
})

When configured like this, your function receives the token as part of the context.clientOptions and can be used to configure a Sanity client.

Deploy the blueprint to create the robot token and assign it to your function:

npx sanity@latest blueprints deploy

pnpm dlx sanity@latest blueprints deploy

yarn dlx sanity@latest blueprints deploy

bunx sanity@latest blueprints deploy

You can define custom roles in the blueprint, then use them to define a robot token. This example defines a role, function-user, then defines a robot as a member of that role, and finally assigns that robot token to the function.

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

export default defineBlueprint({
  resources: [
    defineRole({
      name: 'function-user',
      title: 'Function User',
      permissions: [
        {
          name: 'read-documents',
          action: 'read',
          filter: '_type == "post"',
        },
        {
          name: 'write-documents',
          action: 'update',
          filter: '_type == "post"',
        },
      ],
    }),
    
    defineRobotToken({
      name: 'my-robot',
      memberships: [
        {
          resourceType: 'project',
          resourceId: 'YOUR_PROJECT_ID',
          roleNames: ['function-user'],
        },
      ],
    }),
    defineDocumentFunction({
      name: 'my-function',
      robotToken: '$.resources.my-robot.token',
      // ... rest of config
    }),
  ]
})

Create custom roles with only the permissions your function needs, as shown in "Define custom roles."

The actual token value is managed by Blueprints and never stored in your repository.

Use Node.js v24.x locally to match the Functions runtime and avoid unexpected behavior.

Set robotToken to a string reference such as $.resources.ROBOT_NAME.token, not an object or function call.

@sanity/blueprints only checks that robotToken is a string. It doesn't check that the reference names a robot token in your blueprint, so a typo in the name isn't caught when the blueprint is validated. If context.clientOptions.token is undefined when your function runs, check that the name in $.resources.ROBOT_NAME.token matches the name of a defineRobotToken resource.

The robot's roles don't permit the operation. Review memberships.roleNames and ensure the assigned roles grant the necessary permissions.