mastra-ai/mastra · error · HTTPException

Admin access required

Error message

Admin access required

What it means

Thrown as a 403 by the GET /auth/roles/:roleId/permissions handler when the caller's permissions, read from requestContext under MASTRA_USER_PERMISSIONS_KEY, do not include the wildcard '*' or '*:*'. Only callers with a full-admin wildcard permission may resolve a role's permission set.

Source

Thrown at packages/server/src/server/handlers/auth.ts:799

  method: 'GET',
  path: '/auth/roles/:roleId/permissions',
  requiresAuth: true,
  responseType: 'json',
  pathParamSchema: rolePermissionsPathSchema,
  responseSchema: rolePermissionsResponseSchema,
  summary: 'Get permissions for a role',
  description:
    'Returns the resolved permissions for a specific role. Only accessible by admin users. Used by the "View as role" feature.',
  tags: ['Auth'],
  handler: async ctx => {
    try {
      const { mastra, requestContext, roleId } = ctx as any;

      // Check that the caller is an admin
      const callerPermissions: string[] = requestContext?.get(MASTRA_USER_PERMISSIONS_KEY) ?? [];
      const isAdmin = callerPermissions.some((p: string) => p === '*' || p === '*:*');
      if (!isAdmin) {
        throw new HTTPException(403, { message: 'Admin access required' });
      }

      const rbac = getRBACProvider(mastra);
      if (!rbac?.getPermissionsForRole) {
        throw new HTTPException(404, { message: 'RBAC provider does not support role permission resolution' });
      }

      const permissions = await rbac.getPermissionsForRole(roleId);
      return { roleId, permissions };
    } catch (error) {
      if (error instanceof HTTPException) throw error;
      return handleError(error, 'Error getting role permissions');
    }
  },
});

// ============================================================================
// GET /auth/permission-patterns

View on GitHub (pinned to 75dd419e61)

Solutions

1. Grant the caller the wildcard permission '*' (or '*:*') in your RBAC configuration for the role they belong to.
2. Confirm your auth middleware populates MASTRA_USER_PERMISSIONS_KEY in requestContext for authenticated users.
3. Use an admin service account/token when programmatically querying role permissions.
4. If admin-only access is unintended for this endpoint, adjust the handler gating in your fork or wrap it behind your own admin surface.

Example fix

// before: caller role permissions
['agent:read', 'workflow:run']

// after: grant admin wildcard to the operator role
['*', 'agent:read', 'workflow:run']

const perms: string[] = requestContext?.get(MASTRA_USER_PERMISSIONS_KEY) ?? [];
const isAdmin = perms.some(p => p === '*' || p === '*:*');
if (!isAdmin) throw new Error('This endpoint requires the admin wildcard permission (* or *:*)');

function hasAdminWildcard(permissions: unknown): permissions is string[] {
  return Array.isArray(permissions) && permissions.some(p => p === '*' || p === '*:*');
}

try {
  const { permissions } = await getRolePermissions(roleId);
} catch (e) {
  if (e.status === 403 && /Admin access required/.test(e.message)) {
    throw new Error('Use an admin (wildcard-permission) token to query role permissions.');
  }
  throw e;
}

When it happens

Trigger: Calling GET /auth/roles/:roleId/permissions while authenticated as a user whose permission list lacks '*' (or '*:*') — e.g. a user with only scoped permissions like 'agent:read', or an unauthenticated/unrecognized user yielding an empty permission list.

Common situations: Testing the RBAC endpoint with a normal user account or a service token with narrow scopes; forgetting to grant the admin wildcard to an operator role; permission key not set in requestContext because auth middleware didn't populate it.

Related errors

• Attaching a database requires the admin role in your organiz
• You need the admin role in this organization to manage datab
• Access denied: durable run belongs to a different resource
• Not found
• Not found

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/10439cdb5dbc6201. Report an issue: GitHub.