Front-end permission checks that match server rules

Why this breaks so often

Permission bugs usually start with one bad assumption: if the UI hides an action, the app is safe. It is not. A hidden button only changes what people see. It does not stop someone from calling the same API from another screen, a saved request, or the browser console.

One action often shows up in more than one place. A refund might appear on the order page, in a payment details drawer, in a bulk actions menu, and in a customer support dashboard. User management can spread even wider: an "Edit role" button on the team page, an invite flow, a quick action in search results, and a profile settings screen. If each screen checks permissions in its own way, they drift fast.

That drift gets worse when front-end permission checks grow from small shortcuts into copied logic. One page checks for "admin." Another checks for "canRefund." A third checks whether the user belongs to the support team and the order is less than 30 days old. All three may look reasonable, but only one can match the server rules. The browser should help with UX, not invent policy.

Role changes create another common break. A support agent opens the app in the morning. At noon, an admin removes refund access. If the page never refreshes its permission data, the refund button may stay visible for hours. The click still fails if the server does its job, but the user sees a broken flow and loses trust. The opposite bug is just as bad: access gets granted, but the UI still acts locked.

A simple refund example shows the problem clearly. The server rule might say: finance managers can refund any paid order, and support leads can refund only up to $100 within 14 days. The UI often turns that into something sloppy like "show refund if role is manager or support." That looks close enough until a support agent sees a refund action on a 6-month-old $900 order. They click, the server blocks it, and now the product feels inconsistent.

This is why a thin UI permission mirror matters. The browser needs enough information to show or hide actions, disable forms, and explain why something is blocked. It should mirror the server, not compete with it.

What the browser should and should not do

The browser should help people move through the screen without confusion. It can hide a button, disable a menu item, or skip an action the user cannot take. That makes the product feel clear and predictable.

Front-end permission checks are for guidance, not authority. They shape the UI so people do not keep clicking things that will fail anyway.

The final decision always belongs to the server. If someone opens developer tools, edits a request, or calls the API by hand, the browser cannot stop them. The server has to check the same action again and return a clear yes or no.

A simple rule works well: the browser decides what to show, and the server decides what is allowed. Once teams blur that line, bugs creep in fast.

Take a small admin panel. A support agent can view customer records but cannot delete them. The browser should hide the Delete button or show it as unavailable. If the agent still sends a delete request another way, the server must reject it.

When that rejection happens, keep the message plain. "You do not have permission to delete this record" is enough. Most users do not need a code, a policy name, or an internal reason.

The browser also should not contain secret rules. Do not ship private logic that reveals fraud checks, internal approval thresholds, or hidden account states. Anything in browser code can be read, copied, and tested.

That does not mean the client mirror must be empty. It should carry only the small amount of permission data the screen needs, such as whether the user can edit, archive, or invite others. Keep it narrow. If a rule depends on sensitive data or complex business logic, let the server evaluate it and return only the result.

This split keeps the UI fast and keeps authorization honest. Users get a smoother screen, and your system still stays safe when someone pushes past the browser.

Keep one source of truth on the server

The server should own every permission rule. If a user can edit an invoice, approve a refund, or invite a teammate, the server decides that once and applies it everywhere. The browser can mirror that decision for a better experience, but it should never invent its own version of the rules.

Teams get into trouble when they split logic across places. A backend route checks one role name, a React component checks another, and six weeks later nobody knows which rule is right. The fix is boring, and that is why it works: write permission rules in one server layer and treat that layer as the source for both API behavior and UI hints.

Use clear action names and keep them identical across the stack. If the API talks about project.edit, the UI should use project.edit too. Do not call it canUpdateProject in one place and edit_project in another. Matching names save time, cut guesswork, and make front-end permission checks much easier to trust.

A good pattern is to return allowed actions with the same data the page already needs. If a page loads a project, the response can include the project fields plus a short list of actions the current user may take. Then the UI can decide whether to show an Edit button, disable a dangerous action, or hide admin-only controls without making up its own policy.

A simple response might include:

• the resource data
• the current user role, if the page needs to show it
• a list or map of allowed actions
• a reason for denial when the UI should explain why something is blocked

You also want a record of denied actions on the server. When users keep trying something they cannot do, that tells your team a lot. Maybe the UI exposed the wrong button. Maybe a role is missing one action people expect. Maybe your naming drifted and the mirror fell out of sync.

If you log denials with the action name, resource type, and user role, patterns show up fast. That makes the rules easier to fix before they turn into support tickets.

Mirror only what the UI needs

A good UI permission mirror is small and boring. The browser does not need your full policy model. It needs enough detail to decide whether to show an "Edit", "Refund", or "Invite" button, and what message to show when a task is blocked.

Use front-end permission checks for real actions, not for guessing intent from a role name. Action-based flags are easier to read and safer to wire into buttons, menus, and empty states. "canEditProject" tells the UI exactly what to do. "role = admin" leaves too much room for wrong assumptions.

Match each check to a task a person can actually perform:

• edit a record
• refund a payment
• invite a teammate
• approve a request
• export data

Some access depends on the record itself, not just the person. A support agent might refund a payment only when the payment is in the right state. A manager might edit an order until it ships, but not after. In those cases, send the record state the screen already needs, or send the final flag the server computed from that state.

A simple payload often works better than a clever one. If a payment page needs to know whether to show a refund button, the response can include fields like "status": "captured" and "canRefund": true. That is enough for the UI. It is also easy to inspect in dev tools when something looks wrong.

Do not send the whole rule tree, every inherited role, or a list of policy exceptions. That makes the response noisy and pushes policy logic into the browser. Once that happens, client and server rules start to drift.

Keep the payload small enough that a developer can read it in a few seconds. If someone opens a network response and cannot tell why a button is hidden, the mirror is too complicated. Small permission objects are easier to test, easier to debug, and less likely to lie to the user.

A good rule is simple: send only what the current screen needs to render the next obvious action.

Build the UI checks step by step

Start by loading the permission mirror with the first page data. If a page shows a customer record, the same response can include a small permission block like canEdit, canDelete, and canInvite. That keeps front-end permission checks fast and stops the awkward flash where the page shows every action for a split second, then hides half of them.

Keep the browser's job small. The server decides who can do what. The browser reads those answers and shapes the page around them.

Small guard helpers make this easier to maintain. Wrap buttons, tabs, and menu items in tiny checks instead of scattering if statements across the whole page. A helper should stay boring and direct: read the permission flag, then render, disable, or hold the control until the data arrives.

A simple pattern works well:

• Load permissions with the record data.
• Show a loading state while permissions are unknown.
• Hide controls that make no sense for the current user.
• Disable controls when the user should see the action but cannot use it yet.
• Re-check permissions after any event that can change access.

Hide and disable mean different things, so choose on purpose. Hide an "Admin settings" tab if the user should never enter that area. Disable a "Publish" button if the user has publishing rights in general but cannot publish this draft until required fields are complete. That difference helps people understand the product instead of guessing.

Unknown state needs its own rule. Do not default to "allowed" while the page loads. If permissions have not arrived yet, show a skeleton, a placeholder, or a disabled control with no click action. That prevents UI bugs and avoids training users to click buttons that will fail a second later.

Refresh the mirror after anything that can change access. A save can change record state. A role update can unlock or remove actions. A record reload can bring new policy results from the server. For example, if a manager approves an expense, the "Edit" button may need to disappear right after the save because the record is now locked.

When these checks stay close to the UI and update with fresh server data, the page feels consistent. People stop seeing actions they cannot use, and you avoid the false impression that the browser owns authorization.

Keep the mirror in sync

A UI permission mirror starts to fail as soon as it stops moving with real state. Users sign in, switch accounts, gain access, lose access, or change a record from one status to another. If the browser keeps old permission data for too long, the screen starts lying.

Refresh permission data every time identity changes. After sign-in, fetch a fresh snapshot before you show protected buttons and forms. Do the same when someone switches workspace, team, or account. On logout, clear all cached checks tied to that user. If you skip that step on a shared device, the next person can see the wrong UI for a few seconds, which is enough to cause confusion.

Record status can change permissions just as much as user role. A person may edit an order while it is "draft" and lose that right once it becomes "approved". When the status changes, update the local mirror right away or fetch the new permission state from the server. A full page reload is too late.

A few sync rules cover most cases:

• Re-fetch after sign-in and account switch.
• Recompute or re-fetch when a record changes status.
• Clear cached checks on logout.
• Drop old permission data when the server returns a new version or timestamp.

Two-tab testing catches bugs that normal happy-path testing misses. Open the same record in both tabs. In tab A, change the record status or switch to another account. Then go back to tab B and try the old action. Good front-end permission checks will update the screen or fail closed and ask for fresh data. Bad ones keep showing actions that no longer match server-side authorization.

One simple example: tab A marks a support ticket as closed. Tab B still shows "Reply" because it has an old mirror in memory. The fix is not a bigger client rule set. The fix is sync. Use a refetch after mutation, listen for cross-tab storage events or a broadcast message, and keep the cache short-lived.

If the browser mirror is thin and disposable, stale state becomes a small UX glitch instead of a security risk.

A simple example

Picture an invoice screen with two roles: staff and managers. Staff can read invoice details, download a copy, and check payment history. They cannot refund anything.

Managers can do more, but only in a narrow case. They can refund an invoice only when that invoice is still open.

That gives you a clean split between what the browser shows and what the server decides. The browser can use a small UI permission mirror like this: staff users never see the Refund button, while managers see it only on open invoices.

This keeps front-end permission checks useful without turning them into fake security. The page feels right for each person, but the server still owns the rule.

A normal flow looks like this:

• Staff opens invoice #1842 and sees the invoice details.
• The page hides the Refund button because the UI mirror says canRefund = false.
• A manager opens the same invoice and sees the Refund button only if the status is open.
• When the manager clicks Refund, the server checks the role and the current invoice status again.

That last check matters most. Anyone can change browser code, replay a request, or call the API from another client. If a staff user sends a refund request by hand, the server must reject it. If a manager sends a refund request for a closed invoice, the server must reject that too.

Mid-flow changes are common. A manager may open an invoice at 10:00, see that it is open, and click Refund at 10:03. In those three minutes, another system or teammate may have changed the invoice status.

When that happens, do not pretend the refund worked or leave the user with a vague error. Show a plain message: "This invoice is no longer open, so you cannot refund it." Then refresh the invoice data and update the button state.

That is the whole pattern in small form: hide actions the user cannot take, show actions they probably can take, and let the server make the final call every time.

Mistakes that cause drift

Drift starts when the UI grows faster than the rule model. A team adds one check to a button, another to a menu, and a third to a form field. Soon, each component carries its own version of the truth. Two screens that should behave the same start to disagree, and users notice.

The most common bug is rule copy and paste. One component checks canEditInvoice, another checks user.role === "manager", and a modal adds one more exception for owner. Each line looked harmless when someone wrote it. Together they create front-end permission checks that no one can explain with confidence.

Roles also tempt teams into making the model too simple. Real access often depends on the record itself: status, owner, region, payment state, or whether someone already approved it. A support agent may edit a draft ticket but not a locked one. A finance lead may refund an order before settlement, but not after. If the UI only asks whether the person is an admin, it will drift from server-side authorization very quickly.

Special admin cases make this worse. Teams often hardcode "admins can always do this" in the browser because it fixes a demo or unblocks one internal user. Later, the server keeps stricter logic, or a second admin type appears, and the UI permission mirror starts lying.

Caching causes quieter bugs. If permission data lasts longer than the session, users can keep seeing edit actions after logout and login, role changes, or record updates. Keep the mirror short-lived. Refresh it when identity changes, when the record changes, and when the server says access changed.

The last mistake is confusing presentation with protection. A disabled button only changes the page. It does not stop a direct request, a replayed API call, or a script in the browser console. Hide or disable actions to reduce confusion, but let the server decide every time.

A quick smell test helps:

• Two components check different fields for the same action
• A role check ignores record status
• The UI has an admin bypass that the API does not know about

Thin UI checks are easier to trust. They read a small permission payload from the server and use it the same way everywhere.

Quick checks before release

Right before release, test the app like a skeptical user. Permission bugs usually hide in small places: a button that still shows, a stale tab that still works, or an error message that says almost nothing.

Start with a plain inventory. Every control that can change data, reveal private data, or affect billing needs a matching server rule. If you cannot point from a guarded button to the rule that backs it, treat that gap as a bug.

• Click through each screen and match every guarded button, menu item, and bulk action to a server rule.
• Change a test user from one role to another and confirm the screen updates the way your product promises.
• Keep an old tab open, change the user's role in another session, then retry the same action from the stale tab.
• Read each denied-action message out loud and fix anything vague, cold, or confusing.
• Write down which actions need both a UI check and a hard server reject.

That last point matters more than teams expect. Hiding a button is only a convenience. The server still has to reject the request when someone uses an old tab, a copied request, or a client state that did not refresh.

A short action list helps expose weak spots. Teams often forget one of these:

• delete a record
• export private data
• invite or remove users
• change billing or plan settings
• view admin logs or internal notes

Denied messages deserve a quick edit pass. "Access denied" is technically true, but it leaves people stuck. "You no longer have permission to export this report. Refresh the page or ask an admin for access" is much clearer.

If front-end permission checks and server-side authorization disagree anywhere, users will find it fast. Catching that mismatch before release saves support time and avoids the worst kind of bug: a screen that says no while the API still says yes.

What to do next

Pick one risky flow and clean that up first. Billing, team settings, user removal, and role changes are good places to start because mistakes there confuse users fast and can create real access problems.

A small first pass works better than a full rewrite. If you try to fix every screen at once, the team usually ends up with more drift, not less. One flow is enough to prove the pattern.

Use plain action names before you touch code. Write them the way a person would say them:

• view invoices
• change plan
• invite team member
• remove team member
• edit company settings

Then check each action in two places. The server decides whether the action is allowed. The UI only mirrors that answer so the page can hide, show, disable, or explain the action in a way that makes sense.

That is the practical next step for front-end permission checks. Keep the browser thin. If the server rule changes, the UI mirror should change with it, not invent its own logic.

Make drift review part of every release. It does not need a big process. During QA or release review, ask a few direct questions: does the button state match the API result, does the error message still make sense, and did anyone add a new role or exception without updating the mirror?

A simple rule helps: every new protected action should ship with three things at the same time - a server rule, a UI mirror, and one test that proves they match. That one habit catches a lot of messy edge cases.

If your team has already collected years of mixed rules, an outside review can save time. Oleg at oleg.is reviews product flows as a fractional CTO and helps teams line up UI checks with server-side authorization, especially when the rules have grown across several screens, roles, and older APIs. A short review of one risky flow is usually enough to show where the drift starts.