Vue 3 routing guards for role-based access: practical patterns

What route guards actually solve (and what they do not)

Route guards do one job well: they control navigation. They decide whether someone can enter a route, and where to send them if they cannot. That improves UX, but it is not the same thing as security.

Hiding a menu item is only a hint, not authorization. People can still type a URL, refresh on a deep link, or open a bookmark. If your only protection is “the button is not visible”, you have no protection.

Guards shine when you want the app to behave consistently while blocking pages that should not be shown, like admin areas, internal tools, or role-based customer portals.

Guards help you:

• Block pages before they render
• Redirect to login or a safe default
• Show a clear 401/403 screen instead of a broken view
• Avoid accidental navigation loops

What guards cannot do is protect data by themselves. If an API returns sensitive data to the browser, a user can still call that endpoint directly (or inspect responses in dev tools) even if the page is blocked. Real authorization has to happen on the server too.

A good target is to cover both sides: block pages and block data. If a support agent opens an admin-only route, the guard should stop navigation and show “Access denied”. Separately, your backend should refuse admin-only API calls, so restricted data is never returned.

Choose a simple roles and permissions model

Access control gets messy when you start with a long list of roles. Begin with a small set people actually understand, then add finer permissions only when you feel real pain.

A practical split is:

• Roles describe who someone is in your app.
• Permissions describe what they can do.

For most internal tools, three roles cover a lot:

• admin: manage users and settings, see all data
• support: handle customer records and responses, but not system settings
• viewer: read-only access to approved screens

Decide early where roles come from. Token claims (JWT) are fast for guards but can go stale until refreshed. Fetching the user profile on app start is always current, but your guards must wait until that request finishes.

Also separate your route types clearly: public routes (open to everyone), authenticated routes (require a session), and restricted routes (require a role or permission).

Define access rules with route meta

The cleanest way to express access is to declare it on the route itself. Vue Router lets you attach a meta object to each route record so your guards can read it later. This keeps rules close to the pages they protect.

Pick a simple meta shape and stick to it across the app.

const routes = [
  {
    path: "/admin",
    component: () => import("@/pages/AdminLayout.vue"),
    meta: { requiresAuth: true, roles: ["admin"] },
    children: [
      {
        path: "users",
        component: () => import("@/pages/AdminUsers.vue"),
        // inherits requiresAuth + roles from parent
      },
      {
        path: "audit",
        component: () => import("@/pages/AdminAudit.vue"),
        meta: { permissions: ["audit:read"] },
      },
    ],
  },
  {
    path: "/tickets",
    component: () => import("@/pages/Tickets.vue"),
    meta: { requiresAuth: true, permissions: ["tickets:read"], readOnly: true },
  },
]

For nested routes, decide how rules combine. In most apps, children should inherit parent requirements. In your guard, check every matched route record (not only to.meta) so parent rules are not skipped.

One detail that saves time later: distinguish between “can view” and “can edit”. A route might be visible to support and admins, but edits should be disabled for support. A readOnly: true flag in meta can drive UI behavior (disable actions, hide destructive buttons) without pretending it is security.

Prepare auth state so guards behave reliably

Most guard bugs come from one issue: the guard runs before the app knows who the user is.

Treat auth like a small state machine and make it the single source of truth. You want three clear states:

• unknown: app just started, session not checked yet
• logged out: session check finished, no valid user
• logged in: user loaded, roles/permissions available

The rule: never read roles while auth is unknown. That is how you get flashes of protected screens or surprise redirects to login.

Decide how session refresh works

Pick one refresh strategy and keep it predictable (for example: read a token, call a “who am I” endpoint, set the user).

A stable pattern looks like this:

• On app load, set auth to unknown and start a single refresh request
• Resolve guards only after refresh finishes (or times out)
• Cache the user in memory, not in route meta
• On failure, set auth to logged out
• Expose a ready promise (or similar) that guards can await

Once this is in place, the guard logic stays simple: wait for auth to be ready, then decide access.

Step by step: implement route-level authorization

A clean approach is to keep most rules in one global guard, and use per-route guards only when a route truly needs special logic.

1) Add a global beforeEach guard

// router/index.js
router.beforeEach(async (to) => {
  const auth = useAuthStore()

  // Step 2: wait for auth initialization when needed
  if (!auth.ready) await auth.init()

  // Step 3: check authentication, then roles/permissions
  if (to.meta.requiresAuth && !auth.isAuthenticated) {
    return { name: 'login', query: { redirect: to.fullPath } }
  }

  const roles = to.meta.roles
  if (roles && roles.length > 0 && !roles.includes(auth.userRole)) {
    return { name: 'forbidden' } // 403
  }

  // Step 4: allow navigation
  return true
})

This covers most cases without scattering checks across components.

When beforeEnter is the better fit

Use beforeEnter when the rule is genuinely route-specific, like “only the ticket owner can open this page” and it depends on to.params.id. Keep it short and reuse the same auth store so behavior stays consistent.

Safe redirects without opening holes

Redirects can quietly undo your access control if you treat them as trusted.

The common pattern is: when a user is logged out, send them to login and include a returnTo query param. After login, read it and navigate there. The risk is open redirects (sending users somewhere unintended) and loops.

Keep the behavior simple:

• Logged-out users go to Login with returnTo set to the current path.
• Logged-in but unauthorized users go to a dedicated Forbidden page (not Login).
• Only allow internal returnTo values you recognize.
• Add one loop check so you never redirect to the same place.

const allowedReturnTo = (to) => {
  if (!to || typeof to !== 'string') return null
  if (!to.startsWith('/')) return null
  // optional: only allow known prefixes
  if (!['/app', '/admin', '/tickets'].some(p => to.startsWith(p))) return null
  return to
}

router.beforeEach((to) => {
  if (!auth.isReady) return false

  if (!auth.isLoggedIn && to.name !== 'Login') {
    return { name: 'Login', query: { returnTo: to.fullPath } }
  }

  if (auth.isLoggedIn && !canAccess(to, auth.user) && to.name !== 'Forbidden') {
    return { name: 'Forbidden' }
  }
})

Avoid leaking restricted data during navigation

The easiest leak is loading data before you know the user is allowed to see it.

In Vue, this often happens when a page fetches data in setup() and the router guard runs a moment later. Even if the user gets redirected, the response might still land in a shared store or flash on screen.

A safer rule is: authorize first, then load.

// router guard: authorize before entering the route
router.beforeEach(async (to) => {
  await auth.ready() // ensure roles are known
  const required = to.meta.requiredRole
  if (required && !auth.hasRole(required)) {
    return { name: 'forbidden' }
  }
})

Also watch out for late requests when navigation changes quickly. Cancel requests (for example with AbortController) or ignore late responses by checking a request id.

Caching is another common trap. If you store “last loaded customer record” globally, an admin-only response can be shown later to a non-admin who visits the same screen shell. Scope caches by user id and role, and clear sensitive modules on logout (or when roles change).

A few habits prevent most leaks:

• Do not fetch sensitive data until authorization is confirmed.
• Key cached data by user and role, or keep it local to the page.
• Cancel or ignore in-flight requests when the route changes.

Friendly fallbacks: 401, 403, and not found

The “no” paths matter as much as the “yes” paths. Good fallback pages keep users oriented and reduce support requests.

401: Login required (not authenticated)

Use 401 when the user is not signed in. Keep the message plain: they need to log in to continue. If you support returning to the original page after login, validate the return path so it cannot point outside your app.

403: Access denied (authenticated, but not allowed)

Use 403 when the user is signed in but lacks permission. Keep it neutral and avoid hinting at sensitive details.

A solid 403 page usually has a clear title (“Access denied”), one sentence of explanation, and a safe next step (back to dashboard, contact an admin, switch account if supported).

404: Not found

Handle 404 separately from 401/403. Otherwise people assume they lack permission when the page simply does not exist.

Common mistakes that break access control

Most access control bugs are simple logic slips that show up as redirect loops, flashes of the wrong page, or users getting stuck.

The usual culprits:

• Treating hidden UI as “security”. Always enforce roles in the router and on the API.
• Reading roles from stale state after logout/login.
• Redirecting unauthorized users to another protected route (instant loop).
• Ignoring the “auth is still loading” moment on refresh.
• Mixing up 401 and 403, which confuses users.

A realistic example: a support agent logs out and an admin logs in on the same shared computer. If your guard reads a cached role before the new session is confirmed, you can block the admin incorrectly or, worse, briefly allow access you should not.

Quick checklist before you ship

Do a short pass that focuses on the moments where access control usually breaks: slow networks, expired sessions, and bookmarked URLs.

• Every protected route has explicit meta requirements.
• Guards handle the auth-loading state without flashing protected UI.
• Unauthorized users land on a clear 403 page (not a confusing bounce to home).
• Any “return to” redirect is validated and cannot create loops.
• Sensitive API calls run only after authorization is confirmed.

Then test one scenario end to end: open a protected URL in a new tab while signed out, sign in as a basic user, and confirm you either land on the intended page (if allowed) or a clean 403 with a next step.

Example: support vs admin access in a small web app

Imagine a helpdesk app with two roles: support and admin. Support can read and reply to tickets. Admin can do that too, plus manage billing and company settings.

• /tickets/:id is allowed for support and admin
• /settings/billing is allowed only for admin

Now a common moment: a support agent opens a deep link to /settings/billing from an old bookmark. The guard should check route meta before the page loads and block navigation. Because the user is logged in but lacks the role, they should land on a safe fallback (403).

Two messages matter:

• Login required (401): “Please sign in to continue.”
• Access denied (403): “You do not have access to Billing Settings.”

What must not happen: the billing component mounts, or billing data is fetched, even briefly.

Role changes mid-session are another edge case. If someone is promoted or downgraded, do not rely on the menu. Re-check roles on navigation and decide how you will handle active pages: refresh auth state when the profile changes, or detect role changes and redirect away from pages that are no longer allowed.

Next steps: keep access rules maintainable

Once the guards work, the bigger risk is drift: a new route ships without meta, a role gets renamed, and rules become inconsistent.

Turn your rules into a tiny test plan you can run whenever you add a route:

• As Guest: open protected routes and confirm you land on login without seeing partial content.
• As User: open a page you should not access and confirm you get a clear 403.
• As Admin: try deep links copied from the address bar.
• For each role: refresh on a protected route and confirm the result is stable.

If you want one extra safety net, add a dev-only view or console output that lists routes and their meta requirements, so missing rules stand out immediately.

If you are building internal tools or portals with AppMaster (appmaster.io), you can apply the same approach: keep route guards focused on navigation in the Vue3 UI, and enforce permissions where the backend logic and data live.

Pick one improvement and implement it end to end: tighten data-fetch gating, improve the 403 page, or lock down redirect handling. The small fixes are the ones that stop most real-world access bugs.