Installation

Add zynactra/access to a product: the CLI, the SDK for your stack, Cerbos, the database and the first admin.

Adding access to a product takes an afternoon. The order matters: manifests first, then the runtime, then the UI. The example services are complete versions of every step, so copy from them freely.

Install the CLI and the SDK

The zaccess CLI generates policies and runs policy tests. It needs Go, and zaccess test also needs the cerbos binary on PATH (or in CERBOS_BIN).

go install github.com/zynactra/access/go/cmd/zaccess@latest

go get github.com/zynactra/access/go

The packages are on GitHub Packages. Point the @zynactra scope at it in the product's .npmrc, with a token that has read:packages:

.npmrc

@zynactra:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

pnpm add @zynactra/access @zynactra/access-drizzle pg
pnpm add @zynactra/access-nest   # NestJS services

ESM, Node 22 or later. NestJS needs experimentalDecorators; injection uses explicit @Inject(TOKEN), so emitDecoratorMetadata is not required.

pnpm add @zynactra/access-react
pnpm add @zynactra/ui lucide-react   # only for the admin screens

The admin screens need @zynactra/ui 0.3 or later, set up as in its installation guide, with <Toaster> from @zynactra/ui/toast mounted once at the app root.

Write the manifests

Three files, next to each other in the product:

zaccess.yaml: where the manifests are and where generated files go.
access/access.yaml: the product manifest, with scope types and system roles.
access/plugins/<area>/access.yaml: one resource manifest per area of the product, with its resource kinds, attributes and actions.

Manifests walks through each file; the manifest reference lists every field.

Generate and test

zaccess gen    # policies, schemas, access.manifest.json, constants, policy test scaffolds
zaccess test   # policy tests (fails until every condition has one)

Commit the generated files. CI runs zaccess check -verify (generated files are current) and zaccess test. See Testing.

Run Cerbos next to the service

Cerbos runs as a sidecar serving the generated policies directory, with schema enforcement on and decision logs to stdout. Copy the examples' cerbos.yaml and docker-compose.yml:

cerbos.yaml

server:
  httpListenAddr: ":3592"
storage:
  driver: disk
  disk:
    directory: /policies
    watchForChanges: true
schema:
  enforcement: reject
audit:
  enabled: true
  accessLogsEnabled: false
  decisionLogsEnabled: true
  backend: file
  file:
    path: stdout

Pin Cerbos 0.57.0, the version zynactra/access is tested against, and leave engine.lenientScopeSearch off: a missing org policy must deny. Deploying covers production.

At startup: apply the access schema migrations to the product's Postgres, sync the permission catalog, create the Access instance, the admin service, the access API under /access and the NOTIFY listener. Then guard routes and check records.

Two pieces come from the product itself:

The subject. After your auth middleware verifies the token, build { userId, orgId, idp, groups }. Access never sees tokens, and permissions are never in them.
The resolver. PrincipalAttrs returns per-user values for prefix scopes (a reporting path); ExpandSet expands set scopes (an org unit to everything below it). Both read the product's own tables. See Scopes.

Give each org its first admin

zaccess bootstrap-admin -org org_acme -user u_founder

It only works while the org has no access admin; everything after that goes through the admin API. Assign employee (or your baseline role) to members during onboarding, or map the IdP's all-staff group to it. See Administering access.

Add the UI

AccessProvider at the root, useCan and <Can> around controls, <AccessAdmin /> on a settings page. See React and Admin screens.

Checklist for CI

A Postgres service and the cerbos binary.
ACCESS_REQUIRE_LIVE=1, so tests that need them fail instead of skipping.
zaccess check -verify and zaccess test.
The service's own tests, in strict mode.