@mastra/core/dist/docs/references/docs-studio-auth.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# Studio auth

When you configure [authentication](https://mastra.ai/docs/server/auth) 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](https://mastra.ai/docs/server/auth/simple-auth) for a minimal setup:

```typescript
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](https://mastra.ai/docs/server/auth) for a full list of supported providers.

## How it works

Setting [`server.auth`](https://mastra.ai/reference/configuration) 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:

```typescript
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`:

```typescript
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](https://mastra.ai/contact) for more information.

## Related

- [Auth overview](https://mastra.ai/docs/server/auth): Full list of supported auth providers.
- [Studio deployment](https://mastra.ai/docs/studio/deployment): Deploy Studio to production.
- [Custom API routes](https://mastra.ai/docs/server/custom-api-routes): Control authentication on individual endpoints.