Integrating permission checks into your user interface

This documentation is for an as-yet unreleased version of Cerbos. Choose 0.51.0 from the version picker at the top right or navigate to https://docs.cerbos.dev for the latest version.

It’s a common requirement to make permission checks in the user interface layer of your application. For example, you might want to hide the "Edit" button if the current user isn’t allowed to edit the corresponding resource.

You can tackle this by checking the user’s permissions in the back end of your application and including the results in your API responses, by calling the Cerbos PDP directly from the browser, or by evaluating your policies in the browser.

Checking permissions in the user interface is not a substitute for performing checks in the back end.

Including permissions in API responses

You can add a permissions field to relevant API responses, and populate it by calling the Cerbos PDP’s CheckResources API with multiple actions. For example, an API response from a blog application might look like this:

{
  "blog_post": {
    "title": "Why are we building Cerbos?",
    "author": "Emre Baran & Charith Ellawala",
    "permissions": {
      "edit": true,
      "delete": false
    }
  }
}

This pattern can be readily tailored to your requirements. It’s a great way to ensure that the front and back ends of your application agree on your policy rules.

Calling the Cerbos PDP from the browser

The Cerbos PDP API is available via REST, so you can perform permissions checks directly from the browser. The @cerbos/http JavaScript SDK wraps the REST API to make it easier to integrate into your application.

Exposing the PDP to the internet has security and performance implications. An attacker could use the API to probe your authorization policies much more easily than through your user interface. You could mitigate this to some extent by keeping the PDP behind a reverse proxy that authenticates and rate-limits API calls. You might also want to use a separate deployment with only a subset of your policies.

Evaluating policies in the browser

You can use Cerbos Hub’s embedded PDPs to evaluate your authorization policies directly in the browser. This allows you to perform permission checks on the front end without changing the back end.

Handling CORS

If you call the Cerbos PDP directly from a browser, you may encounter CORS (Cross-Origin Resource Sharing) errors. This happens when your web application and the Cerbos PDP are served from different origins.

To resolve this, configure CORS in your Cerbos server configuration:

server:
  cors:
    allowedOrigins:
      - "https://your-app.example.com"
    allowedHeaders:
      - "content-type"
      - "authorization"

See server configuration for all available CORS options.

Avoid setting allowedOrigins to * in production. Be as specific as possible with the origins you allow.

If your Cerbos PDP sits behind a reverse proxy (such as Nginx or Envoy), ensure that only one layer is adding CORS headers. Duplicate Access-Control-Allow-Origin headers will cause browsers to reject the response.

Should you call Cerbos from the browser?

For most applications, the recommended approach is to call Cerbos from your back end and include the permission results in your API responses. This has several advantages:

  • Your Cerbos PDP doesn’t need to be exposed to the internet.

  • You avoid CORS configuration entirely.

  • Sensitive context data (like resource attributes) stays server-side.

  • Permission checks and data fetching happen in a single round trip.

See Including permissions in API responses above for this approach.

Calling Cerbos directly from the browser can be useful during development or for applications that use the Cerbos PDP as a shared service accessible from multiple front-end clients. If you take this approach, be aware that any data sent in the request (principal attributes, resource attributes) is visible to the end user via browser developer tools.