# `MishkaCmsWeb.Runtime.Plugs.RequirePermission`
[🔗](https://github.com/mishka-group/mishka_cms_core/blob/v0.0.1/lib/mishka_cms_core/runtime/plugs/require_permission.ex#L5)

Refuses a request whose user holds none of the permissions a route requires.

The required list is any-of: holding one entry is enough. An entry is a permission name, which a
held wildcard covers (`admin:dashboard:*` covers `admin:dashboard:runtime:page`), or `{:under, prefix}` for
anyone holding anything under `prefix` — `MishkaCmsCore.Accounts.Checks.AccessPermissions`
answers, with the conn's Ash context: behind
`MishkaCmsCore.Runtime.Plugs.AdminSurfacePlug, surface: :api` an `admin:api:…` name counts and an
`admin:dashboard:…` one does not, and elsewhere the reverse. An empty list admits nobody.

    # The admin API's docs: anyone holding anything under admin:api
    plug MishkaCmsWeb.Runtime.Plugs.RequirePermission,
      permissions: [{:under, "admin:api"}],
      on_denied: :json

    # One area on the screens
    plug MishkaCmsWeb.Runtime.Plugs.RequirePermission,
      permissions: ["admin:dashboard:runtime:media"]

## Options

  * `:permissions` — the required list.
  * `:on_denied` — `:redirect` (the default) flashes "You don't have permission to access this
    page" and redirects to `/`; `:json` answers a JSON:API `403`, for the `/api/json` and `/gql`
    pipelines, which fetch no flash.

## Events

- `web:request:before_permission_gate` — the conn, before it is asked.
- `web:request:permission_gate` — the conn it answered with, with `%{authorized: boolean}` as its
  meta.

# `call`

Passes the conn when its `:current_user` holds any required permission, else refuses it.

# `init`

The required list and how a refusal is answered, from `:permissions` and `:on_denied`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*