How access works
Distinguish authentication, workspace roles, operation scopes and data grants
Access is evaluated for a caller and an operation on a specific resource. A successful sign-in or visible project name is not permission to perform every operation or read every bound data source.
You need a Semogram account for human membership. Services use workspace API keys. OAuth-connected assistants operate with the signed-in person's current membership and permissions; connecting the assistant does not create membership or additional grants.
Decision layers
| Layer | Human/OAuth caller | API-key caller |
|---|---|---|
| Identity | Verified account and current membership | Valid, unexpired, unrevoked key |
| Workspace | Membership in the selected workspace | Workspace bound to the key |
| Operation | Role and applicable explicit grants | Selected API scopes |
| Project | Current workspace membership/access checks | Selected project IDs, or all projects when empty |
| Shared resources | Applicable member/operation checks | Restricted key also needs workspaceResources |
| Bound reads | Named permissions required by the binding | Custom readPermissions in addition to API scopes |
| Writes | Actor permissions and applicable policy/approval | Scopes plus accountable actor and applicable policy/approval |
Owners/admins have broad management permission. Members' OAuth MCP permissions begin with the implemented read permissions and incorporate applicable explicit read/write grants; an OAuth member gets exactly the scopes their membership grants. org:manage is not gained by inserting that text into a custom grant list. Tool discovery can hide actions the caller cannot use.
For example, every Member can view plugin installations, the catalog and authoring runs, but installing, editing, checking, removing or authoring plugins needs a plugins:write member grant. The app, MCP and the database apply the same rule.
Example: an equipment query reader
A service key belongs to Factory operations and permits Maintenance only. It has projects:read, queries:read and queries:execute. The equipment read binding requires maintenance:read.
The service can discover/query Maintenance when it also holds maintenance:read. Without it, the operation scope can pass while the bound data read fails. Adding maintenance:read does not permit queries:write. Removing Maintenance from its allowlist can deny the project even if the binding grant remains.
If it separately needs to inspect a workspace data endpoint, grant the matching endpoint scope and workspaceResources; granting all workspace resources also reaches shared resources used by other projects, subject to scopes. It is not a per-endpoint allowlist.
Diagnose before changing access
Read the actual error, identify the caller kind, workspace, project, action and resource. Check key expiry/revocation or membership first, then scopes, project restrictions and binding grants. For writes inspect workspace mode, approved policy revision, actor grant and external privileges.
Do not infer access from a previously cached result. Grant removal is checked on later reads, including continuation pages. A page token does not preserve revoked permission.