Workspaces — Proto Reference (workspace.v1)

already_held is true when the user already had a seat (idempotent no-op).

at_least_consistency_token, when set, demands the batch observe state at least as fresh as the token (from a prior WriteRelationTuples). Empty = read latest. A malformed or foreign-shard token is rejected.

error is non-empty when the item could not be evaluated (e.g. invalid arguments); allowed is then false.

subject_set asks whether a USERSET (e.g. group:cohort-7#member, or a service-account set) has the relation, rather than a concrete user. It is used iff subject_user_id is empty; exactly one of the two must be set. The answer is "does the queried userset intersect the relation's effective userset" — true if the set is structurally included, or if any concrete member of the set has the relation.

context carries request-time attributes that CONDITIONAL grants are evaluated against (e.g. {"age": 9, "consent": true, "ip": "1.2.3.4", "now": "2026-06-16T00:00:00Z"}). Unset = no context; conditional grants then fail closed, while unconditional grants are unaffected.

at_least_consistency_token, when set, demands the check observe state at least as fresh as the token (from a prior WriteRelationTuples). Empty = read latest. A malformed or foreign-shard token is rejected.

optional owning workspace; empty for a standalone group.

max_check_reads: 0 leaves the project on the global default budget. A positive value overrides it and must be >= the same floor as the global (see GATEWAY_MAX_CHECK_READS).

slug is optional; the server derives one from display_name when empty.

tenant_id is accepted for call-shape symmetry but IGNORED: erasure spans every tenant of the project.

at_least_consistency_token, when set, demands the expansion reflect state at least as fresh as the token (from a prior WriteRelationTuples). Empty = read latest. A malformed or foreign-shard token is rejected.

limited is false when no limit is configured for the sku (unlimited).

workspace_id optionally scopes the group to a workspace (a company's internal groups). Empty for project-level / standalone groups (a B2C user's "family" list).

token is returned ONLY from CreateInvitation so the caller can deliver it out of band; it is never echoed by ListInvitations.

optional: restrict to groups owned by this workspace.

at_least_consistency_token, when set, demands the listing reflect state at least as fresh as the token (from a prior WriteRelationTuples). Empty = read latest. A malformed or foreign-shard token is rejected.

model_json is the project's authorization model as a JSON document. Empty means the project uses the built-in default model.

data_region, when set, pins the project's data to a region/storage target. An instance configured for a different region refuses to serve it (fail closed). Empty means unpinned. Multi-region storage ROUTING is forward- compat; today this is recorded, validated, and enforced as a serving guard.

max_check_reads, when > 0, overrides the global per-request read budget (GATEWAY_MAX_CHECK_READS) for this project's Check/Expand/ListObjects evaluations. 0 means unset: the project uses the fleet-wide default.

optional: restrict to tuples whose subject is this concrete user.

at_least_consistency_token, when set, demands the read reflect state at least as fresh as the token (from a prior WriteRelationTuples). Empty = read latest. A malformed or foreign-shard token is rejected.

expires_at, when set, makes the grant time-bounded: the tuple stops granting access once this instant passes (enforced at read time, so Check and tuple-to-userset walks both honor it). Unset = never expires. Expiry is mutable metadata, NOT part of tuple identity: re-writing the same tuple with a new expires_at updates it; deletes still match by identity.

condition_name, when set, makes the grant CONDITIONAL: it applies only if the named built-in condition (e.g. consent_granted, age_at_least, ip_in_cidrs, not_after) evaluates true against condition_params (bound here) and the request-time CheckRequest.context. Unset = unconditional. The condition is grant metadata, not part of tuple identity: re-writing the tuple replaces it; deletes still match by identity. Unknown name / missing input / ill-typed value all DENY (fail closed).

condition_params are the static parameters bound to the condition at write time (e.g. {"min_age": 13} for age_at_least).

limit is absent when the sku is unlimited (no cap configured); present (including 0, which admits no seats) when a cap is set.

limit, when present, sets the cap (must be >= 0; 0 admits no seats). When ABSENT, the sku's limit is CLEARED, returning it to unlimited — this is the only way to undo a previously-set cap.

data_region: empty leaves it unchanged (like name/model). Setting it repins the project; a repin converges across a horizontally-scaled fleet only after the resolver TTL (~30s), so it is not instantaneous.

clear_data_region, when true, reverts the project to region-agnostic (unpinned). Mutually exclusive with a non-empty data_region. This is the explicit "unpin" path, since an empty data_region means "leave unchanged".

max_check_reads: 0 leaves it unchanged (like name/model). A positive value overrides the global per-request read budget and must be >= the same floor as the global default. The override converges across a horizontally-scaled fleet only after the resolver TTL (~30s), so it is not instantaneous.

clear_max_check_reads, when true, reverts the project to the global default budget. Mutually exclusive with a positive max_check_reads. This is the explicit "reset" path, since a 0 max_check_reads means "leave unchanged".

For LEAF nodes: the concrete subjects and usersets at this node.

For UNION / INTERSECTION nodes: the child subtrees. Empty for EXCLUSION (which uses `include` / `exclude` instead).

The userset this node expands.

For LEAF nodes: true if the public wildcard subject is present.

For EXCLUSION nodes only: the include leg (the base set) and the exclude leg (subjects removed from it). The effective set is `include` minus `exclude`. Unset for every other node type.

project_id is the configuration/model shard (identity ADR-0002).

tenant_id is the data-isolation shard within the project; empty = default.

project_id scopes every tuple in the batch; empty = default project.

consistency_token is an opaque "zookie" naming the shard's write sequence reached by this batch. Pass it to a later Check/Expand/ListObjects/ BatchCheck/ReadRelationTuples as at_least_consistency_token to demand read-after-write (observe at least this write). Optional to use.