Read permissions
Grant the named permissions required by ontology read bindings
Custom read grants are names evaluated by ontology read bindings, such as maintenance:read. They represent access to configured bound data. They are not API operation scopes and do not change workspace roles.
You need a Semogram account as owner/admin to manage member grants, or an authorized org:manage key for the public management API. First inspect the actual binding and its required names. Inventing a grant label without configuring a matching binding does not establish a data policy.
Equipment example
Suppose an equipment binding requires maintenance:read. Maya's account and the equipment-report service key each need their own grant. Giving it to Maya does not also put it on a service key; granting queries:execute to the key does not supply the binding grant.
| Setting | Purpose |
|---|---|
| queries:execute in API scopes | Allows the query invocation operation |
| Maintenance project ID | Allows this project's resources |
| maintenance:read in custom grants | Satisfies the binding's configured data-read requirement |
The query must still use a supported published release, endpoint/capability and external connection. A grant does not install a plugin or grant database credentials.
Set grants
In Member permissions → Manage, or API access → a key's permissions page, edit Custom read grants. Enter one name per line. Preserve needed existing grants, save, then retry a bounded read as the affected caller.
Ask a connected administrator assistant to inspect the binding and caller's current grants, identify missing required names and prepare the complete proposed list. Membership inspection is available through organization_member_list; grant changes are applied through the UI/API, not a fabricated MCP grant-update tool.
For members use PUT /api/v1/members/<USER_UUID>/read-permissions with readPermissions. For keys use PATCH /api/v1/api-keys/<KEY_UUID> with readPermissions. Both require org:manage. The lists replace stored grants rather than incrementally adding one entry.
{"readPermissions":["maintenance:read"]}Limits and revocation
Up to 100 unique grant names are accepted, with at most 200 characters each. Use letters, numbers, dots, underscores, colons and hyphens. Whitespace around names is trimmed and duplicates normalized. An empty list revokes all custom read grants.
Revocation applies to subsequent reads, including continuation pages. Do not assume a previously issued cursor preserves permission. Confirm the caller identity and test both allowed and denied bindings after a change.
See Ontology read bindings for configuring the data side of this relationship.
Binding policies and masking
A binding policy can require one or several permission names, a specific workspace role or an allowed role list. Every declared permission must be present. API keys have no human workspace role, so a role-restricted binding can intentionally exclude them even when they have the named grants.
Supported read masks are none, redact, hash, tokenize and last4. Redact removes the exposed value; hash/tokenize use the deployment's keyed masking configuration; last4 leaves the final four characters visible. Masking affects projection and does not mean the underlying external record was deleted. Inspect whether the selected mask is appropriate for the actual field.
For a field requiring maintenance:read and redaction, a binding policy fragment can be { "permission": "maintenance:read", "maskPolicy": "redact" }. This belongs in the binding's policy configuration, not the member's grant list or a standalone API request. Preserve the binding's full mapping/source definition when editing it. Missing masking configuration or unsupported policy fields should be investigated, not bypassed by dropping the policy.