SaaSLayer

Operations and Audit

Authorization changes can have wide impact. SaaSLayer Permissions includes operational tools for previewing, applying, tracking, and auditing those changes.

Permission rebuilds

Permission checks read a materialized permission document for the principal. Writes that affect access may rebuild or invalidate that document.

Common rebuild triggers:

  • Role assignment or removal
  • Role permission changes
  • Role inheritance changes
  • Policy attachment or update
  • Boundary changes
  • Membership or hierarchy changes
  • Grant creation or revocation

You can inspect a user's materialized state:

GET /users/user-alice/perm-state

Use this when debugging unexpected allows or denies.

Cascades

Some changes affect many principals. For example, changing a widely used role can require rebuilding permissions for every principal with that role.

SaaSLayer Permissions supports asynchronous cascades for large fanout changes. API responses may indicate that a cascade was queued instead of completed synchronously.

Operational guidance:

  • Avoid editing broad roles during high-traffic windows unless the change is urgent.
  • Watch cascade job status after large updates.
  • Prefer smaller scoped roles when possible.
  • Use dry-run and impact previews before destructive changes.

Dry runs

Some write endpoints support dry-run mode. Dry runs show what would change without persisting the mutation.

Use dry runs before:

  • Deleting roles
  • Deleting policies
  • Updating high-impact entities
  • Applying changes from admin tools

Changesets

Changesets group multiple RBAC mutations into a staged workflow. They are useful when a change should be reviewed, previewed, approved, applied, and possibly rolled back as one unit.

Use changesets for:

  • Tenant onboarding changes
  • Role redesigns
  • Policy migrations
  • Large cleanup operations
  • Changes that require approval before apply

History and rollback

Roles and policies expose history endpoints and rollback operations. Use them when a configuration change had unintended effects.

Examples:

GET /roles/role-admin/history
POST /roles/role-admin/rollback

GET /policies/policy-prod-guardrail/history
POST /policies/policy-prod-guardrail/rollback

Keep rollback procedures documented for your own admin operators. Rollback is most useful when your team knows which version was last known good.

Each permission rebuild also snapshots the principal's previous effective permissions (GET /users/{id}/history). Snapshots expire 90 days after they are superseded. A deployment can change this with PERMISSIONS_PERMISSION_HISTORY_RETENTION_DAYS (a whole number of days; 0 keeps snapshots forever). An invalid value stops the service at startup. For a long-term record of who changed what, use the audit log below.

Audit logs

Audit logs record RBAC operations with actor, target, scope, event type, and details where available.

Useful queries:

GET /audit/actor/user-admin
GET /audit/target/ROLE/role-billing-manager
GET /audit/scope/tenant-acme-prod
GET /audit/recent
GET /audit/events?eventType=cascade.*

Use audit logs to answer:

  • Who changed this role?
  • Which policies were edited recently?
  • What changed in this tenant?
  • Which operations caused a permission cascade?
  • Was a denied support action attempted?

Safe-change checklist

Before a broad authorization change:

  1. Identify affected roles, policies, tenants, and principals.
  2. Run a dry run or impact preview where available.
  3. Use a changeset for multi-step changes.
  4. Apply during an operationally safe window.
  5. Watch cascade jobs and audit logs.
  6. Test representative permission checks with explain mode.
  7. Keep rollback information close to the change record.