Skip to main content
Page level access control determines who can view a project’s published reports. It is defined in a single access.yaml file at the project root, created for you automatically. The file lives alongside your content, ships through the same git workflow as your pages, and is enforced when readers visit your published reports.
Users with the Developer, Admin, or Org Viewer role can always view all pages, regardless of access.yaml.

​
Who can see your reports

Before you write any rules, it helps to know that an Evidence organization has two kinds of viewers:
  • Internal viewers — typical employees and teammates inside your organization. They are part of the org, hold a role of viewer or higher, and can be added to Groups.
  • External viewers / customers — clients or partners you share dashboards with from outside the company. They are managed under Customers and behave like a kind of group, but with one important difference: they are excluded from any “everyone in the org” rule.

​
Groups

Groups let you organize users for easier access management. Instead of granting page or project access to individual users, you can grant access to a group. Create groups from the Settings → Team page. A group’s ID is set at creation and cannot be changed, so references in access.yaml keep working even if you rename the group’s display name.

​
Customers

You can add external viewer users to Customers in your organization. Customers behave like a group, but are excluded from any “everyone in the org” ($org) rule — they must always be granted access explicitly.

​
Groups vs Customers

GroupsCustomers
Allowed RolesViewer, Org Viewer, Developer, AdminViewer only
”Everyone in the Organization” AccessIncludedExcluded

​
The access.yaml schema

The file lives at the project root: access.yaml. Here is a complete example covering every supported construct: 
project:
  grants:
    viewers:
      - $org # built-in: every internal org member with viewer or higher
      - alice@example.com # user (email)
      - marketing # group ID

pages:
  reports/q1-overview: # page path = directory slugs + file slug, no extension
    inherit: true # additive (default): project audience + grants below
    grants:
      viewers:
        - finance

  reports/internal:
    inherit: false # override: ONLY the grants below see this page
    grants:
      viewers:
        - alice@example.com
        - leadership
Page grants are additive by default. A page’s audience is the project audience plus anything listed under the page. To restrict access on a single page, set inherit: false — only the principals you list there will see that page.

​
Top-level keys

  • project — the project-wide audience. Required. Use project: with grants: viewers: [] for an admins-and-developers-only project.
  • pages — per-page overrides keyed by full page path. Optional. Pages not listed here inherit the project audience entirely.

​
viewers lists

The grants.viewers list defines who can see a project or page. It can contain four kinds of principals, mixed in any order:
  • Users — referenced by email, e.g. alice@example.com. Must resolve to an org member.
  • Groups — referenced by group ID, e.g. marketing. Group IDs are lowercase letters, digits, and hyphens. Create groups on the Groups page; a group’s ID is set at creation and cannot be changed, so existing references keep working even if the display name is renamed.
  • Customers — your external customer groups, referenced by their group ID just like internal groups.
  • $org — a built-in group meaning every internal member of your organization with viewer role or higher.
$org does not include customers. It grants access to every internal member of your organization with viewer role or higher, and nothing else. Customers must be granted access explicitly — either by email or by the customer group they belong to.
$org is project-level only. Using it under a page entry is rejected — to make a single page org-wide visible, leave inherit: true and grant $org at the project level.

​
inherit (pages only)

Controls whether the project’s viewers can also see this page:
  • inherit: true (default) — project viewers see this page, plus anyone you list under grants.viewers.
  • inherit: false — project viewers do not see this page. Only the principals you list under grants.viewers can see it.

​
Page paths

Use the full path within the project: directory slugs joined by /, then the file slug, no extension.
  • Valid: summary, reports/sales/monthly, q1-overview
  • Invalid: Reports/Sales (uppercase), /leading-slash, trailing-slash/, with spaces
Page paths must be lowercase, matching the form used in your published URLs.

​
Closed by default

To declare an admins-and-developers-only project, write a project block with an empty viewers list: 
project:
  grants:
    viewers: []
This is the minimum valid file. An entirely empty file, a comments-only file, or a file that omits the top-level project: key (for example, a pages-only file) is rejected by validation — see Validation below. We require the explicit project: declaration so that a forgotten or accidentally-truncated file fails loudly instead of silently locking your viewers out. To declare “open to the org”, you must write it explicitly: 
project:
  grants:
    viewers:
      - $org

​
Examples

​
1. Open to the entire org

Every internal org member with viewer role or higher can see every page. 
project:
  grants:
    viewers:
      - $org

​
2. Restricted to one group

The whole project is restricted to a single group. Useful for sensitive projects (finance, security, legal) where the audience is a tightly-defined team. 
project:
  grants:
    viewers:
      - finance
Anyone outside the finance group (other than developers and admins, who always retain access) gets a 404 on every page.

​
3. Restricted to multiple groups + named individuals

Same pattern, but the audience is a few groups plus a couple of specific people not in any of them. 
project:
  grants:
    viewers:
      - finance
      - leadership
      - alex@example.com
      - jordan@example.com
Lists can mix users, group IDs, and $org freely.

​
4. Open project, but one page is restricted

The project is open to the org, but a specific page (e.g. an executive dashboard or financial detail) is restricted to a smaller group. Use inherit: false so the project audience does not spill onto this page. 
project:
  grants:
    viewers:
      - $org

pages:
  reports/board-meeting:
    inherit: false
    grants:
      viewers:
        - executives
Everyone in the org sees the project; only executives see reports/board-meeting.

​
5. Restricted project, with a few pages opened to a wider audience

The project is restricted to one group, but specific pages need a broader audience. Use inherit: true (the default) plus extra grants — the page audience becomes “the project’s audience plus these extras”. 
project:
  grants:
    viewers:
      - finance

pages:
  reports/quarterly-summary:
    grants:
      viewers:
        - leadership
  reports/headcount:
    grants:
      viewers:
        - hr
        - leadership
finance sees every page (including the two listed). leadership additionally sees quarterly-summary and headcount. hr only sees headcount.

​
6. Per-customer pages

When you publish customer-specific pages in the same project (e.g. an “Acme dashboard” and a “Globex dashboard”), grant your internal team at the project level and each customer on their own page. Because inherit defaults to true, account managers automatically see every page — including customer pages — without being listed on each one. 
project:
  grants:
    viewers:
      - account-managers

pages:
  customers/acme:
    grants:
      viewers:
        - customer-acme
  customers/globex:
    grants:
      viewers:
        - customer-globex
Each customer sees only their own dashboard; account managers (the project-level audience) see all pages.
Pair page-level access with Row-Level Security for true data isolation between customers. Page level access decides which pages a customer can open; Row-Level Security decides which rows of data they see when they query. For customer-facing reports where each customer should only see their own data, use them together: per-page access in access.yaml, RLS rules on the underlying tables.

​
Editing access.yaml

access.yaml is a regular project file — edit it in the Studio editor (with live validation, autocomplete, and AI-sidebar awareness) or in your own environment for GitHub-connected projects. Changes flow through the same commit and publish workflow as your pages: rules only go live once they reach your published branch.

​
Validation

Studio validates access.yaml to make sure your access rules are well-formed and resolve against your org. Validation checks that:
  • The file exists and contains a top-level project: block with a grants.viewers list (the minimum valid file is project: with grants: viewers: [])
  • The YAML parses and matches the expected schema
  • Every email refers to a real org member
  • Every group ID refers to a real group
  • Every page path refers to a real page
On feature branches we warn so you can stage work in progress. Before changes reach your default branch we block, so broken yaml can never affect real viewers.
SurfaceWhenOn failure
Editor liveEvery keystrokeInline squiggles, autosave proceeds
Studio commit on a feature branchOn commitWarn with dialog. Choose Commit anyway to land WIP, or fix first.
Studio commit on default branchOn commitBlock with dialog. No override.
Studio publish (merge feature → default)On publishBlock with dialog. No override.
GitHub PRPR opened, reopened, or new commits pushedCheck Evidence: access.yaml Validation fails with annotated lines
Default-branch merge appliedAfter mergeBanner + admin email; viewer access is paused until the failure clears

​
Failure recovery

If access.yaml is malformed or missing on the default branch after a merge, Studio cannot apply the new rules. The behavior is:
  1. Viewer access is paused. Until the next successful publish, only admins and developers can open the project. Viewers (internal and external) are blocked.
  2. Admins are notified. An email is sent to all organization admins, and a banner appears in Studio on every page until the failure is resolved.
  3. Fix the file: edit access.yaml to resolve the validation errors, commit, and merge. The next successful publish automatically restores viewer access.
The strictness of the upstream validators means this state should be unreachable through normal use — the Studio commit/publish gates and the GitHub PR check all block invalid yaml before it can land. The failsafe exists for force-pushes, history rewrites, and unusual merge paths.

​
Branch behavior

You can use branches to preview access changes before they go live. Each branch uses its own access.yaml, so:
  • When you open a preview link for a branch, the audience is resolved from that branch’s access.yaml.
  • Changes on a feature branch do not affect the published access rules.
  • The rules only go live once the branch is merged into the published branch.
This lets you stage and review access changes the same way you stage and review content changes.

​
CI check on pull requests

When the project is connected to GitHub, every PR runs the Evidence: access.yaml Validation check alongside the existing Evidence: Markdown Validation check.
  • The check parses access.yaml from the PR head, validates schema, and resolves references against the project’s users, groups, and pages.
  • Errors appear as annotations on the offending lines in the PR file diff.
  • A missing access.yaml fails the check.