{"record":{"id":"10439cdb5dbc6201","repo":"mastra-ai/mastra","slug":"admin-access-required","errorCode":null,"errorMessage":"Admin access required","messagePattern":"Admin access required","errorType":"http","errorClass":"HTTPException","httpStatus":403,"severity":"error","filePath":"packages/server/src/server/handlers/auth.ts","lineNumber":799,"sourceCode":"  method: 'GET',\n  path: '/auth/roles/:roleId/permissions',\n  requiresAuth: true,\n  responseType: 'json',\n  pathParamSchema: rolePermissionsPathSchema,\n  responseSchema: rolePermissionsResponseSchema,\n  summary: 'Get permissions for a role',\n  description:\n    'Returns the resolved permissions for a specific role. Only accessible by admin users. Used by the \"View as role\" feature.',\n  tags: ['Auth'],\n  handler: async ctx => {\n    try {\n      const { mastra, requestContext, roleId } = ctx as any;\n\n      // Check that the caller is an admin\n      const callerPermissions: string[] = requestContext?.get(MASTRA_USER_PERMISSIONS_KEY) ?? [];\n      const isAdmin = callerPermissions.some((p: string) => p === '*' || p === '*:*');\n      if (!isAdmin) {\n        throw new HTTPException(403, { message: 'Admin access required' });\n      }\n\n      const rbac = getRBACProvider(mastra);\n      if (!rbac?.getPermissionsForRole) {\n        throw new HTTPException(404, { message: 'RBAC provider does not support role permission resolution' });\n      }\n\n      const permissions = await rbac.getPermissionsForRole(roleId);\n      return { roleId, permissions };\n    } catch (error) {\n      if (error instanceof HTTPException) throw error;\n      return handleError(error, 'Error getting role permissions');\n    }\n  },\n});\n\n// ============================================================================\n// GET /auth/permission-patterns","sourceCodeStart":781,"sourceCodeEnd":817,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/auth.ts#L781-L817","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Grant the caller the wildcard permission '*' (or '*:*') in your RBAC configuration for the role they belong to.","Confirm your auth middleware populates MASTRA_USER_PERMISSIONS_KEY in requestContext for authenticated users.","Use an admin service account/token when programmatically querying role permissions.","If admin-only access is unintended for this endpoint, adjust the handler gating in your fork or wrap it behind your own admin surface."],"exampleFix":"// before: caller role permissions\n['agent:read', 'workflow:run']\n\n// after: grant admin wildcard to the operator role\n['*', 'agent:read', 'workflow:run']","handlingStrategy":"validation","validationCode":"const perms: string[] = requestContext?.get(MASTRA_USER_PERMISSIONS_KEY) ?? [];\nconst isAdmin = perms.some(p => p === '*' || p === '*:*');\nif (!isAdmin) throw new Error('This endpoint requires the admin wildcard permission (* or *:*)');","typeGuard":"function hasAdminWildcard(permissions: unknown): permissions is string[] {\n  return Array.isArray(permissions) && permissions.some(p => p === '*' || p === '*:*');\n}","tryCatchPattern":"try {\n  const { permissions } = await getRolePermissions(roleId);\n} catch (e) {\n  if (e.status === 403 && /Admin access required/.test(e.message)) {\n    throw new Error('Use an admin (wildcard-permission) token to query role permissions.');\n  }\n  throw e;\n}","preventionTips":["Grant the '*' or '*:*' wildcard to operator/admin roles that need RBAC introspection.","Use dedicated admin service tokens for automation calling this endpoint.","Verify auth middleware populates MASTRA_USER_PERMISSIONS_KEY before assuming a permission bug.","Hide admin-only endpoints behind admin UI gates to avoid confusing 403s."],"tags":["rbac","authorization","http-403"],"backgroundTag":"insufficient-permissions","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}