Mastra Studio gets its own SSO, separate from server auth

Separating Studio access from server access

According to Mastra, teams often want to treat authentication for the Mastra server and for Studio differently. External users of an agent typically need access to the server, while team members need access to Studio. The new feature is meant to make that split easier to set up.

Before this change, SSO could be configured on the server and Studio would inherit it. There was no separate SSO permissioning available for Studio itself, according to the company.

How the configuration works

To replace the default platform sign-in with a custom provider, users set MASTRA_PLATFORM_STUDIO_AUTH=disabled. Studio then uses the provider defined in studio.auth.

Mastra published an auth matrix describing how each combination of settings protects Studio on the Mastra platform:

• If MASTRA_PLATFORM_STUDIO_AUTH is not set, platform sign-in is used, regardless of the other settings.
• If it is disabled and studio.auth is set, Studio login uses studio.auth.
• If it is disabled, studio.auth is not set and server.auth is set, Studio login uses server.auth.
• If it is disabled and neither studio.auth nor server.auth is set, Studio is public.

Mastra warns that disabling platform sign-in without configuring studio.auth or server.auth leaves Studio publicly accessible.

Getting started with WorkOS

The announcement walks through setup using WorkOS as the example. First, install the provider package with npm install @mastra/auth-workos@latest. The feature requires @mastra/[email protected] or later, which was added in PR #17722.

Next, the provider is added to studio.auth in the Mastra config, for example studio: { auth: new MastraAuthWorkos() }. The server.auth setting stays separate and continues to protect server endpoints.

Finally, credentials go into the .env file: WORKOS_API_KEY, WORKOS_CLIENT_ID, WORKOS_REDIRECT_URI and WORKOS_COOKIE_PASSWORD, along with MASTRA_PLATFORM_STUDIO_AUTH set to disabled. Mastra points to its documentation pages on bringing your own auth, Studio auth, the auth overview and WorkOS for full configuration options.

What it means for teams

For teams running agents on Mastra, the change allows internal staff to sign in to Studio with an identity provider they already use, while the server can keep a different authentication setup for outside users. Teams that disable platform sign-in should make sure at least one of studio.auth or server.auth is configured, since the fallback is an open Studio.