Using 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.

Prerequisites:

• Functions run on Node.js v24.x.
• 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.

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.
• A token is generated and managed by Sanity.
• Functions reference the token like so: $.resources.<robot-name>.token.
• 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.

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

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

You can find a list of available roles for your project with the Access API, or by viewing the roles in 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: 'abc123',
          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.

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 with 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: 'abc123',
          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 the role example above.

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.

Ensure the value is exactly $.resources.<robot-name>.token (a string, not an object or function call).

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