Skip to content

Commit 35d29b6

Browse files
authored
chore: clarify the standalone auth is experimental (#539)
1 parent 857f8ee commit 35d29b6

File tree

1 file changed

+14
-5
lines changed

1 file changed

+14
-5
lines changed

packages/core/guides/AuthenticationGuide.md

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# SDK Authentication Guide
22

3-
This document outlines the various authentication types supported by the Sanity SDK, catering to different usage contexts like embedded dashboard apps, Studio integrations, and standalone applications.
3+
This document outlines the various authentication types supported by the Sanity SDK, catering to different usage contexts like embedded dashboard apps, Studio integrations, and in very limited cases, standalone applications.
44

55
## ✨ High-Level Overview
66

@@ -17,12 +17,21 @@ The primary interactive authentication flow involves redirecting the user to `sa
1717
This mechanism applies to both third-party Sanity Apps and internal Sanity
1818
applications (e.g., Canvas, Media Library).
1919

20+
- **When should you use this?** Most of the time this is the best option. It is for building a Sanity App that is running in the Sanity Dashboard.
21+
2022
- **Studio Mode:** Leverages Studio's own auth context (token or cookie)
2123
when the SDK is used within the Studio application.
2224

23-
- **Standalone:** Supports manually provided tokens (stable for backends,
24-
requires care for stamped tokens on frontends). ⚠️ The built-in web login flow (`sanity.io/login`) has
25-
significant limitations for apps on custom domains due to origin restrictions.
25+
- **When should you use this?** This is only for using the SDK within the Sanity Studio application.
26+
27+
- **Standalone (Experimental):** Supports manually provided tokens (stable for backends,
28+
requires care for stamped tokens on frontends).
29+
30+
- **When should you use this?** For most developers, this is not the best option. It is only for using the SDK within a standalone application that is not running in the Sanity Dashboard and is not part of the Studio. It likely requires you to write custom code to handle the login flow and the callback.
31+
32+
- ⚠️ The built-in web login flow (`sanity.io/login`) has significant limitations for apps on custom domains due to origin restrictions.
33+
34+
## 🔑 Key Concepts & Technical Details
2635

2736
## 🚦 Authentication Types
2837

@@ -78,7 +87,7 @@ The primary interactive authentication flow involves redirecting the user to `sa
7887

7988
- `clientStore` will configure clients based on the available token or implicitly rely on cookies if `withCredentials` is set appropriately. Clients are only configured for the project-specific endpoint.
8089

81-
### 3. Standalone Applications
90+
### 3. Standalone Applications (Experimental)
8291

8392
- 🎯 **Use Case:** External web applications using the SDK that operate independently of the Sanity Dashboard or Studio (e.g., SDK Explorer, custom internal dashboards). These applications are **not** running inside the Dashboard iframe or as part of the Studio build and they are not hosted on Sanity's domains.
8493

0 commit comments

Comments
 (0)