Access
Product access
Understand why a person can or cannot reach a product, and what a membership on a product actually is.
Access to a product is always a concrete membership on that product — one row naming one participant, with one role. Nothing anywhere grants someone “all products” as a rule evaluated at request time, so the list of members of a product is the complete answer to who can reach it.
This is what keeps the product boundary described in work with products hard.
What a membership record carries
| Field | What it means |
|---|---|
| Role | Exactly one role. Combining roles is done by defining a role with the combined permissions, not by stacking two roles on one member. |
| Status | A membership is active or not. Only active memberships count. |
| Expiry | Optional. An expired membership stops applying and the member stops seeing the product, without anything being deleted. |
| Source | Either an explicit share to that one person, or a membership materialized from their organization role. |
A member is either a human user or an AI agent; agents are scoped to a product, not to an organization.
Any member of a product can list its members, whatever their role: organization_product_list-members — GET /governance/api/v1/products/:productId/members. The roles available on a product come from organization_product_list-roles — GET /governance/api/v1/products/:productId/roles.
How an organization role turns into product access
| Organization role | What they reach |
|---|---|
| Owner, admin | A membership on every product in the organization. It is created for real: when a product is created, every owner and admin gets one, and when someone is promoted, they get one on each existing product. |
| Member | Nothing until a specific product is shared with them. Without a share the product is not merely hidden — requesting it returns 404, exactly as for someone outside the organization. |
The effect is “owners and admins see everything”, but the mechanism is ordinary memberships you can list and inspect.
Changes propagate the same way:
- Demoting an owner or admin to member removes the memberships that came from their organization role and leaves any explicit shares intact.
- Removing someone from the organization removes their membership and their grants.
- Ownership itself never changes hands:
ownercan be set when a person is invited, but the role-change call takes onlyadminandmember, so no later call raises a member to owner.
How someone is given a product
A person is a member of the organization first and reaches a product only if something grants it. There is no product-level invitation and no link you can hand around: an invitation is to the organization, and the grant rides along with it or follows afterwards.
| Call | What it grants |
|---|---|
organization_member_invite | Brings someone into the organization and grants products in the same operation, through productShares. Each entry may carry an expiresAt. |
organization_member_share-product | Grants one product to an existing member, with an optional expiresAt and explicit allow and deny permissions. |
organization_product_set-access | Grants or changes a product role for an existing member, at admin, member, viewer or one of the organization’s named roles. It carries no expiry, and the owner role is not among the values it accepts. |
share-product is the more capable of the two calls that grant to an existing member, because its expiresAt lets access end on a delivery date without anyone having to remember to remove it. set-access is the one to reach for when the question is which role a member holds on a product.
Revoking has the matching pair. organization_member_unshare-product removes an explicit share, and organization_product_revoke-access removes a grant from the product’s side. Neither one touches the access an owner or admin holds through their organization role — that is lifted by changing the role, not at the product.
To read the result from the product’s side, organization_product_list-access — GET /governance/api/v1/products/:productId/access — returns the explicit grants and their roles, the owners and admins who inherit access, the members holding none yet, and the named roles a grant can be handed at. Its canManage field says whether the caller may change any of it.
Two limits to plan around
Both matter most when the person you are granting a product to is a client rather than a colleague.
The invoice does not move. Budgets and caps are scoped inside the organization that holds the product, so a shared product always bills the organization it lives in. There is no way to change the payer, and no way to move the product to an organization that would pay for it instead.
Every member can read the roster. organization_member_list returns the organization’s members with their roles and their product grants, and that read sits outside the per-product grant model — no custom role, no deny list and no product scoping removes it. Two clients who are guests in the same organization can see each other. When that is unacceptable, each of them needs their own organization, which means creating it before the work starts rather than after.
Next steps
- Share a product with a member: the invite, share and unshare calls, with their parameters.
- Look up what a role grants: the four product roles, the permission key shape and the allow/deny decision.
- Browse the product membership endpoints: every path, method and parameter behind the tools on this page.