Summary

The Authorizing Users page explains the concepts of capabilities, prefixes, and inheritance, but doesn't provide a practical how-to for common access control patterns. Customers are asking how to set this up and getting confused by the two layers (user access vs. task access).

What's missing

A guide covering common patterns like:

1. Restricting a user to a sub-prefix

• Grant user write/admin to acmeCo/team-a/ instead of acmeCo/
• User can only create/modify tasks under that prefix

2. Isolating sub-prefixes from each other (e.g. staging vs. production)

• The distinction between user grants (what tasks you can create) and role grants (what collections a task can access)
• By default, acmeCo/ has write to itself, so all tasks inherit access to everything — restricting the user alone is not enough
• To fully isolate: remove the default tenant-level write-to-self grant, replace with per-sub-prefix grants
• Example: acmeCo/staging/ write to acmeCo/staging/, acmeCo/prod/ write to acmeCo/prod/

3. Additional considerations

• Data plane grants may be needed for sub-prefixes
• Storage mapping inheritance — sub-prefixes inherit from parent, but the UI may not show available prefixes without explicit storage mappings
• The difference between what the UI shows vs. what validation actually enforces

Context

A customer asked how to restrict materializations in a sub-prefix to only access collections within that same sub-prefix. The existing docs didn't answer this, and the answer is nuanced.