Semogram Docs
Workspace managementPeople and access

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

LayerHuman/OAuth callerAPI-key caller
IdentityVerified account and current membershipValid, unexpired, unrevoked key
WorkspaceMembership in the selected workspaceWorkspace bound to the key
OperationRole and applicable explicit grantsSelected API scopes
ProjectCurrent workspace membership/access checksSelected project IDs, or all projects when empty
Shared resourcesApplicable member/operation checksRestricted key also needs workspaceResources
Bound readsNamed permissions required by the bindingCustom readPermissions in addition to API scopes
WritesActor permissions and applicable policy/approvalScopes 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.