Can Netlify restrict a route by an authenticated visitor's role?

Definition: Yes. A Netlify role-based redirect can restrict a path to logged-in visitors whose JSON Web Token contains a permitted role. Netlify documents Netlify Identity and JWT-capable authentication providers as the authentication choices; external providers require an Enterprise plan.

Key facts

• Netlify's Redirect options documentation describes role-based redirects for paths restricted to logged-in visitors with specified roles.
• The same documentation says this access control runs at Netlify's CDN edge, without a round trip to the origin server.
• Netlify's role-based access control documentation allows either Netlify Identity or an external JWT provider, with one JWT provider at a time.
• The role documentation maps Netlify Identity roles to app_metadata.roles and external-provider roles to app_metadata.authorization.roles.

What authentication does Netlify require?

Netlify's documentation updated 17 September 2026 describes role-based access control as a combination of JSON Web Tokens, roles, and redirect rules. A JWT is the signed token issued by an authentication provider after login. Netlify reads user claims in that token when it evaluates access.

Netlify Identity provides the built-in JWT flow. The Identity service generates a JWT and stores it in a cookie named nf_jwt; the cookie is sent automatically with requests to the project. An external provider can also be used when it supports JWT tokens with roles metadata. Netlify names Auth0 and Okta as examples. External-provider setup requires a project JWT secret in the Netlify UI, which Netlify uses to verify access tokens, and the documentation labels the feature as available on Enterprise plans.

Netlify requires JWTs to use the HS256 signing algorithm. The role claims sit under app_metadata, with the default path depending on the provider:

Netlify Identity: app_metadata.roles
External JWT provider: app_metadata.authorization.roles

The documentation says that a custom external-provider role path can be configured through Netlify support.

How does a role condition protect a path?

The role documentation says that a role rule is a regular Netlify redirect rule with a Role parameter. Rules can be placed in a _redirects file or a Netlify configuration file. This _redirects example is the documented pattern for an administrator path and its fallback:

/admin/*  /admin/:splat  200!  Role=admin
/admin/*  /login         401!

The first rule grants access to /admin and everything below it when the JWT includes the admin role. The 200 status changes the response while keeping the requested URL in the browser, and the exclamation mark forces the rule when a file matches the path. The second rule catches visitors who do not match the role and sends them to /login with a 401 status. Several permitted roles can be listed with commas, as in Role=editor,admin.

The same configuration can be expressed in netlify.toml:

[[redirects]]
  from = "/admin/*"
  to = "/admin/:splat"
  force = true
  status = 200
  conditions = {Role = ["editor", "admin"]}

What happens when the role or token changes?

Netlify recommends a fallback rule because an unauthorized visitor sees a raw 404 page without a way to log in when no fallback exists. A fallback can point to a login page or an error page, and the documented example uses /login.

Changing a user's roles does not invalidate the current JWT. The new roles take effect when the token is refreshed, typically on the next login or when the client calls refreshSession(). This timing applies when checking a role change in a live session.

Related terms

• HTTP redirects
• How do I add redirects with Netlify's _redirects file?
• How do I password-protect a Netlify deploy preview?

FAQ

Can Netlify Identity and an external JWT provider run together?

No. Netlify's role documentation says a project may use Netlify Identity or an external provider for JWT authentication, but cannot use both at the same time.

What does an unauthorized visitor see?

Without a fallback rule, the visitor sees a raw 404 page. A fallback such as /admin/* /login 401! sends that visitor to the login path.

Can a cookie condition replace a role condition?

Cookie-based redirects are a separate option. Netlify checks whether a named HTTP cookie exists, regardless of its value, while role-based access reads roles from the authenticated visitor's JWT.

Sources

1. Netlify, "Redirect options", 17 September 2026
2. Netlify, "Role-based access control with JWT", 17 September 2026

---

Check how a page reads to answer engines. Open the GEO score analyzer