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; org:manage is not gained by inserting that text into a custom grant list. Tool discovery can hide actions the caller cannot use.
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.