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

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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 or edit workflows, or alternatively 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. 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.

## Pass a token through the URL

When another application embeds or links to Studio, it can hand over an authorization token through the `auth_header` URL parameter. This is useful when an external host already holds a token and wants to open an authenticated Studio session without showing the login screen.

The `auth_header` value always populates the `Authorization` request header. The parameter sets that one header only, so include any scheme prefix the server expects in the value, such as `Bearer`.

Open Studio with the token in the query string:

```text
https://your-studio-host/?auth_header=Bearer%20your-token
```

Studio handles the token as follows:

- It reads `auth_header` once on load and sends the value as the `Authorization` header on every API request in that session.
- It removes `auth_header` from the address bar while preserving other query parameters and the hash.
- It keeps the token in memory only and never writes it to local storage, so the token stays transient and doesn't persist across page reloads.

The token rides in a URL parameter, so the host application is responsible for how that URL is generated and transmitted. URL parameters can be exposed through browser history and referrer headers, plus server access logs.

## 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 includes 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. A license is optional when using Simple Auth or running locally. Production deployments with third-party providers require a valid EE license from [Mastra sales](https://mastra.ai/contact).

## 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.