Studio Auth
Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference
Published: 2026-05-10 · Source: crawler_authoritative
Tình huống
Mastra Studio documentation for configuring authentication, RBAC, and access control to secure the Studio UI and API routes with login screens and role-based permissions.
Insight
Studio authentication is configured via the server.auth property on the Mastra instance. When configured, Studio automatically displays a login screen and enforces authentication on all API routes including /api/agents/*, /api/workflows/*, and custom routes. Authentication applies to both Studio UI access and direct API calls. Studio detects auth capabilities by calling GET /api/auth/capabilities, which returns available login methods and user info if already authenticated. Supported auth providers include SimpleAuth, Firebase, Clerk, WorkOS, and others. Role-based access control (RBAC) is configured separately via server.rbac using the StaticRBACProvider imported from @mastra/core/auth/ee. Four default roles are available: owner (full access *), admin (read, write, execute), member (read and execute), and viewer (read-only). Permissions follow the pattern {resource}:{action} with optional resource-level scoping. Available resources include agents, workflows, tools, datasets, memory, scores, and observability. Actions are read, write, execute, and delete. External provider roles from Clerk organizations or WorkOS groups can be mapped to Mastra permissions using the roleMapping option. Studio hides actions the user doesn’t have permission for based on their role. Login UI adapts based on provider type: SSO button only, email/password form only, or both.
Hành động
Add an auth provider to your Mastra server configuration. For Simple Auth, import Mastra and SimpleAuth from @mastra/core and @mastra/core/server, then create a Mastra instance with server.auth set to a new SimpleAuth with a users object mapping API keys to user data including id, name, and role. To enable RBAC, also import StaticRBACProvider and DEFAULT_ROLES from @mastra/core/auth/ee, then add server.rbac with a StaticRBACProvider configured with roles and a getUserRoles function. For role mapping from external providers, pass a roleMapping object to StaticRBACProvider mapping provider role strings to permission arrays. Studio Auth features including SSO login, RBAC, and permission-based UI are part of Mastra Enterprise Edition and require a valid EE license for production deployments with third-party providers.
Kết quả
When authentication is configured, Studio displays a login screen and requires authentication for all built-in and custom API routes. With RBAC enabled, Studio hides UI elements and actions the user lacks permission for—viewers won’t see delete buttons, members cannot modify agent configurations. External provider roles are mapped to Mastra permissions for access control decisions.
Điều kiện áp dụng
Studio Auth features work without a license during local development and with Simple Auth. Production deployments using third-party auth providers require a valid Enterprise Edition license.
Nội dung gốc (Original)
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:
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:
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:
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.
Liên kết
- Nền tảng: Dev Framework · Mastra
- Nguồn: https://mastra.ai/docs/studio/auth
Xem thêm: