Authentication with the App SDK

Learn about the mechanisms that enable authentication when building with the App SDK.

The App SDK has two authentication mechanisms and automatically uses the appropriate one based on the context in which it's running. This article provides technical information about each of these mechanisms.

Authentication in the SDK is primarily managed by an authStore, which tracks the user's authentication state (LoggedIn, LoggedOut, LoggingIn, Error). It determines the initial state based on the environment the application is running in — that is, one of:

• A Sanity Dashboard iframe
• Sanity Studio

API client instances, managed by a clientStore, will automatically use the current authentication token from the authStore for requests. The clientStore also handles differentiating between clients configured for 'global' endpoints (such as api.sanity.io) and 'default' (project-specific) endpoints (such as <projectId>.api.sanity.io).

Several different types of authentication tokens are referred to in the course of this article:

Global tokens are not tied to a specific project, but instead to a Sanity user. They include access to all of the user’s organizations and projects. Global tokens are required for accessing global Sanity APIs (e.g., project management), and are used when clientStore configures a client with scope: 'global' or without a projectId.

Project tokens are scoped to a single project (and any of a single project’s datasets). They are used in the Studio mode (described below), and can also be provided manually. These tokens only allow access to project-specific endpoints (e.g. <projectId>.api.sanity.io.

Tokens obtained via the sanity.io/login authentication flow (and thus also from the Sanity Dashboard) are 'stamped' tokens (type=stampedToken). These tokens are refreshed by the App SDK’s refreshStampedToken function. Non-stamped tokens, however, will not be refreshed by the App SDK.

The Sanity Dashboard enables the default and preferred mode of authentication within custom applications, with the Dashboard providing an authentication token to custom applications built with the App SDK. This results in a seamless experience for the end-user.

This mechanism applies to both third-party custom apps and Sanity’s own applications built with the App SDK.

In Dashboard mode, the Sanity Dashboard loads the custom app’s iframe with with an authentication token hash (#token=…) in the iframe’s src URL. When the custom app is initialized, the getAuthCode function (invoked by the App SDK via the SanityApp component) will retrieve and validate this token. If for some reason the token is invalid, the getAuthCode function will request a new token from the Dashboard, and this new token will be used instead. Once a token is validated, it will be stored in the the authStore. No user interaction is required during this exchange — everything is handled automatically, and the process should be completely invisible to an end user.

With the token thus stored in the application’s authStore, it will be used as part of all API client calls made via the App SDK’s hooks, effectively using the current user’s active Dashboard session. This token will be a global, stamped token that is refreshed every 12 hours.

This authentication mode leverages the studio’s own auth context (via a token or cookie). It’s used when the App SDK is used with the Sanity Studio codebase (not the Dashboard iframe) — for example, within custom input components, tools, or plugins integrated directly into the Studio application.

Studio mode is enabled by configuring the studioMode option in the SDK configuration.

import {type SanityConfig} from '@sanity/sdk-react'

const config: SanityConfig = {
  studioMode: {
    enabled: true,
  },
  // rest of config…
}

With this configuration, the authStore will attempt to authenticate using one of two methods.

First, the getStudioTokenFromLocalStorage function will look for an authentication token specific to the Studio session, which will be stored in local storage under the key __sanity_auth_token_${projectId}. This token is project-specific.

If this token is not found, the function checkForCookieAuth is called. This function attempts a request to a Studio backend endpoint to check if a valid HTTP-only session cookie exists. If it does, subsequent API requests managed by the App SDK client will rely on this cookie for authentication.