Studio auth

When you configure authentication on your Mastra server, Studio automatically displays a login screen and enforces access control. One configuration secures both the Studio UI and your API routes.

Without authentication, Studio and all API routes are publicly accessible.

When to use Studio Auth

• Multiple team members need to interact with agents, workflows, and tools through a shared Studio deployment.
• Permissions must restrict who can execute agents, edit workflows, or delete datasets.
• A login screen (SSO, email/password, or both) should gate access to your Studio deployment.

Quickstart

Add an auth provider to your Mastra server configuration. This example uses Simple Auth for a minimal setup:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { SimpleAuth } from '@mastra/core/server'

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({
      users: {
        'my-api-key': {
          id: 'user-1',
          name: 'Alice',
          role: 'admin',
        },
      },
    }),
  },
})

Once configured, Studio shows a login screen and requires authentication for all API requests.

note

Visit the Auth docs for a full list of supported providers.

How it works

Setting server.auth does two things at once:

• Studio UI: Displays a login screen. Depending on the provider, users sign in through SSO, email/password, or both.
• API routes: Requires authentication for all built-in routes (/api/agents/*, /api/workflows/*, etc.) and custom routes. This applies whether requests come from Studio or direct API calls.

Studio detects available capabilities by calling the GET /api/auth/capabilities endpoint. The response tells Studio which login methods to render and, if the user is already authenticated, includes their user info and permissions.

Role-based access control

RBAC lets you control what each user can see and do inside Studio. It's separate from authentication: server.auth handles who the user is, while server.rbac handles what they can do.

Default roles

Mastra ships four default roles. Import them from @mastra/core/auth/ee:

Role	Permissions
owner	Full access (*)
admin	Read, write, and execute
member	Read and execute
viewer	Read-only

Enable RBAC

Use StaticRBACProvider with the default roles or define your own:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { SimpleAuth } from '@mastra/core/server'
import { StaticRBACProvider, DEFAULT_ROLES } from '@mastra/core/auth/ee'

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({
      users: {
        'admin-key': { id: 'user-1', name: 'Alice', role: 'admin' },
        'viewer-key': { id: 'user-2', name: 'Bob', role: 'viewer' },
      },
    }),
    rbac: new StaticRBACProvider({
      roles: DEFAULT_ROLES,
      getUserRoles: user => [user.role],
    }),
  },
})

When RBAC is active, Studio hides actions the user doesn't have permission for. A viewer doesn't see delete buttons; a member can't modify agent configurations.

Permission format

Permissions follow the pattern {resource}:{action}, with optional resource-level scoping:

Pattern	Meaning
*	Full access to everything
*:read	Read all resources
agents:*	All actions on agents
agents:execute	Execute agents only
agents:read:my-id	Read a specific agent by ID

Resources include agents, workflows, tools, datasets, memory, scores, observability, and others. Actions are read, write, execute, and delete.

Map external provider roles

If your identity provider already defines roles (for example, Clerk organizations or WorkOS groups), map them to Mastra permissions with roleMapping:

src/mastra/index.ts

import { StaticRBACProvider } from '@mastra/core/auth/ee'

const rbac = new StaticRBACProvider({
  roleMapping: {
    'org:admin': ['*'],
    'org:member': ['*:read', '*:execute'],
    'org:viewer': ['*:read'],
  },
  getUserRoles: user => user.providerRoles,
})

Login methods

Studio adapts its login screen based on the auth provider:

Provider type	Login UI
SSO only	SSO button (e.g. "Sign in with WorkOS")
Credentials only	Email and password form
Both	SSO button and email/password form

Sign-up can be enabled or disabled per provider. When disabled, Studio hides the sign-up link and forces the sign-in form.

EE licensing

Studio Auth features (SSO login, RBAC, permission-based UI) are part of the Mastra Enterprise Edition. They work without a license during local development and with Simple Auth. For production deployments with third-party providers, a valid EE license is required. Contact sales for more information.

Related

• Auth overview: Full list of supported auth providers.
• Studio deployment: Deploy Studio to production.
• Custom API routes: Control authentication on individual endpoints.