Authentication Design

Core Credentials

Credential	Acquisition	Storage	Purpose
appKey	Defined by the developer as the generator ID	Frontend code	Identifies the current generator for data isolation
uToken	Obtained after user login	Shared-domain utoken cookie	Identifies the user's identity

Request Headers

The SDK automatically includes these headers in every request:

uToken: {User's uToken}
lang: {Value from localStorage LANG_KEY, defaults to 'en'}

TIP

In the current implementation, the X-App-Key header is commented out; the appKey is passed via the category field in the request body to achieve data isolation.

Token Storage

• The SDK now aligns with the community app and consistently reads/writes the shared-domain utoken cookie.
• appKey still isolates business data, but it is no longer part of the token storage key.
• If a legacy __atomm_sdk_token__{appKey} value still exists, the SDK migrates it into the utoken cookie on first read.
• Silently ignored if cookies are unavailable (for example SSR or private mode).

Token Lifecycle

Login → setToken(appKey, token) → Write the `utoken` cookie
Request → getToken(appKey) → Inject into uToken Header
Invalidation → clearToken(appKey) → Clear the `utoken` cookie → Trigger logout
Logout → clearToken(appKey) → passport-client.logout()
Restoration → getToken(appKey) → passportClient.userInfo() validation → Restore status on success
Studio embedding → Read Studio token / listen for UserStateChanged → syncToken() → Stay aligned with the Studio host

Studio Embedded Login State

When a generator is embedded in xTool Studio, the SDK automatically syncs the Studio login state during the auth.ready() initialization flow:

• Wujie micro frontend reads window.$wujie.props.token and subscribes to UserStateChanged on window.$wujie.bus.
• iframe embedding reads the initial token from <iframe name="xTool-Studio-iframe" data-initial="..."> and listens for Studio postMessage UserStateChanged events. atomm://renderer inside Studio Electron is treated as a trusted origin.
• The Studio token takes precedence over the local cache; an empty token from Studio clears the SDK's local login state.

Generators still use sdk.auth.getStatus(), sdk.auth.ready(), and sdk.auth.onChange() to get the final state, regardless of whether they run on the platform web page or inside Studio.

Security Notes

Risk Point	Mitigation
appKey Misuse	The appKey only identifies the app and does not authorize actions; all APIs fail if the user is not logged in.
Malicious Credit Deduction	credits.consume backend validates if the appKey has permission for the requested action.
Cross-App Data Access	Backend isolates data using category (appKey) + uid as a composite dimension.
uToken Leakage	Managed via the shared-domain cookie while the application runs under the platform domain.
Malicious Applications	Code undergoes security scanning + manual review before going live.
Cross-Origin Canvas Tainting	canvas.toDataURL() catches SecurityError and handles it gracefully.