Organization policy, roles and permissions
For developers and administrators who set what an organization's people and agents may do. This page lists every key of an organization's policy, with its type, default and effect; the permissions, roles and principals that decide who may do what to an instruction; and what a legal hold blocks.
Policy keys
An organization's policy is one set of keys, the same for all its workspaces. Each has a default, which holds until an admin sets the key.
| Key | Type | Default | Effect | In the editor |
|---|---|---|---|---|
defaultVisibility | "private" | "internal" | "public" | "private" | The visibility of an instruction created (instructions_create) or copied (instructions_duplicate, instructions_fork) without one. It changes no existing instruction. | Settings ▸ Security ▸ Who can read new instructions |
agentPublish | boolean | false | Agents and services may release versions (instructions_publish) and merge proposals. Off: they are refused with forbidden, "this organization doesn't let agents release versions (policy agentPublish); suggest the change and ask a maintainer". | Settings ▸ Security ▸ Agents may publish |
agentSharing | boolean | false | Agents and services may widen who reads an instruction: make one public (at creation, by a fork or with instructions_visibility_set), add or raise a grant, approve an access request, or make a read link. Off: forbidden, "agents can't widen who reads an instruction here (organization policy agentSharing)". | Over MCP only |
aiAutoPublish | boolean | string[] | false | Agents and services may approve and merge proposals without a person. Only true has an effect: a list of refs is accepted and stored, and counts as off. | Over MCP only |
requireSignedVersions | boolean | false | Stored and shown, and checked by nothing. On instruction.md every version is signed with the organization's key when it is released; a self-hosted server signs only with a signing key set up. To require signatures on a ref, use the ref's own gate, requireSignature. | Developer ▸ Signing ▸ Only signed versions on refs |
memberRole | "none" | "reader" | "contributor" | "maintainer" | "reader" | The default workspace's role a person gets on joining as a member, by invitation, by orgs_members_add or by SCIM, when nothing else names one. none gives no role. It changes no one already there. | Settings ▸ Security ▸ What new members can do |
integrationsOnly | boolean | false | Instructions' MCP servers, skills, agents and services are approved only from the organization's integrations; anything else is marked and not used. true is refused on a plan without the feature. Plans On Team and Enterprise | Settings ▸ Integrations ▸ Only approved integrations |
developerMode | boolean | false | Developer mode in the editor for a member who hasn't chosen their own. A default only: each person's choice wins. Owners and admins on Team and Enterprise have it on by default anyway. | Settings ▸ General ▸ Developer mode for new members |
workspacePeople | boolean | true | The organization's own people are offered in mentions as you write. Also set by orgs_people_directories_set with directory "workspace". | Settings ▸ Integrations ▸ Directories ▸ Offered as you write |
assistant | boolean | true | The editor's assistant may be used on this organization's instructions. Off: nobody uses it on them, whatever is left of any allowance. | Settings ▸ Security ▸ The assistant in the editor |
The policy on agents (agentPublish, agentSharing, aiAutoPublish) applies to the agent and service credentials an organization's people make. It never changes what a person may do.
Read and change the policy
orgs_policy_get returns the policy in force (the defaults with what was set), the defaults themselves, and when the organization last changed.
{
"name": "orgs_policy_get",
"arguments": { "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B" }
} orgs_policy_set merges the keys you send into the policy. A key you don't send stays as it is, and null puts a key back to its default. This call turns off agent publishing and the assistant:
{
"name": "orgs_policy_set",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"policy": { "agentPublish": false, "assistant": false }
}
} It answers as orgs_policy_get does:
{
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"policy": {
"defaultVisibility": "internal",
"agentPublish": false,
"agentSharing": false,
"aiAutoPublish": false,
"requireSignedVersions": false,
"memberRole": "reader",
"integrationsOnly": false,
"developerMode": false,
"workspacePeople": true,
"assistant": false
},
"defaults": {
"defaultVisibility": "private",
"agentPublish": false,
"agentSharing": false,
"aiAutoPublish": false,
"requireSignedVersions": false,
"memberRole": "reader",
"integrationsOnly": false,
"developerMode": false,
"workspacePeople": true,
"assistant": true
},
"updatedAt": "2026-11-22T10:02:17.554Z"
} {
"name": "orgs_policy_set",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"policy": { "defaultVisibility": null, "memberRole": "contributor" }
}
} - Who can do this. An organization's owners and admins, as people, with a token that has the
org:adminscope. Agents can't read or change the policy. See org:admin. - Checked keys. A key that isn't one of the policy's, or a value of the wrong type, is refused with
validation, naming the key.integrationsOnly: trueon a plan without the feature islimit_reached. - Recorded. A change that changes something records an
org.updatedevent, itssubject.keysnaming the keys sent. See Audit trail. - Read as a resource. The same document is
org://<org>/policy. See Resources and addresses.
Roles
Who may do what to an instruction comes down to one permission on this ladder:
none < read < suggest < edit < publish < manage
Each permission includes every one below it. A caller's permission is the highest of what each of these gives, then cut by the limits after them.
- Visibility. A public instruction gives
readto everyone. One visible to Your organization givesreadto the organization's owners, admins, billing members and members, never its guests. - Organization role. The organization's owners and admins have
manageon every one of its instructions, in every workspace. - Workspace role. The role a principal holds in the instruction's workspace gives its permission, unless the instruction turned the workspace baseline off (
workspaceBaseline: false). - Grants. What
instructions_access_setgave the person, the agent, or an organization they are a member of.
Then the limits:
- Agents and services hold
publishat most, whatever they are given. - A token holds at most what its scopes allow:
instructions:readreads,instructions:writeedits,instructions:publishpublishes,instructions:adminmanages. A person's token with no instruction scope is the person. See Sign-in, scopes and tokens. - A token of another organization (an agent credential is its organization's) holds
readat most on this organization's instructions: anything abovereadbecomesreadon a public instruction and nothing on any other. - An app (Sign in with instruction.md) reads at most, and never the draft.
- An archived instruction is read-only to all but those who manage it. One in the trash is seen only by those who manage it.
The draft, its suggestions and its comments are for the people who work on it: visibility gives no one the draft, only the versions. A caller with no permission gets not_found, never forbidden, so a private instruction's existence doesn't show.
Permissions and workspace roles
| Permission | Workspace role | Shown as | Confirmation wording | Adds | The editor says |
|---|---|---|---|---|---|
read | Reader | Reader | Can read | Read its released versions, its refs and history; with a workspace role or a grant, its draft, suggestions and comments too. Follow it, fork it, duplicate it, offer a proposal, ask for more access. | reads the instruction, its suggestions, comments and history |
suggest | Contributor | Contributor | Can propose | Comment, reply and resolve one's own threads; suggest changes (what you type lands as suggestions); withdraw one's own. | proposes changes and comments; a maintainer accepts them |
edit | None (granted only) | Maintainer | Can edit | Edit the draft directly; change its title, description and tags (instructions_update). Granted on its own only to agents and services, whose edits land as suggestions. | |
publish | Maintainer | Maintainer | Can maintain | Accept and reject suggestions, restore a checkpoint, release versions, move and delete refs (not one with gates), schedule releases, approve and merge proposals (never one's own), make and revoke read links. | edits, accepts or rejects changes, publishes versions and promotes one to live |
manage | Admin | Admin | Can manage | Share (instructions_access_set), change visibility, rename, archive, move to the trash and restore, delete for good, transfer, revoke a version, change a ref's gates and the default ref, its fork policy and license, list who has access and who follows it, pause a follower, read its activity and audit. |
"Shown as" is the role an error's details.role names for that permission. "Confirmation wording" is what a sharing confirmation says, such as "Can propose".
How workspace roles work:
- Given or inherited. A role is given in a workspace with
orgs_workspaces_roles_set. In an open workspace other than the default, a member or billing member who holds none there inherits their default-workspace role, at most Maintainer. A restricted workspace is only for the people added to it. - Admin of a workspace manages its instructions, and its people's roles and its settings. It is always given, never inherited.
- Agents hold at most Maintainer in a workspace.
- Guests hold no workspace role: one is refused, "a guest holds no role in a workspace; make them a member first, which takes a seat".
- New members get the policy's
memberRolein the default workspace when nothing names another.
Organization roles
Owner (owner) | Admin (admin) | Billing (billing) | Member (member) | Guest (guest) | |
|---|---|---|---|---|---|
| Takes a seat | Yes | Yes | Yes | Yes | No |
| The organization's instructions | Admin (manage) on every one, in every workspace | Admin (manage) on every one, in every workspace | Read those visible to Your organization; their workspace roles | Read those visible to Your organization; their workspace roles | Only what is shared with them |
| Workspace roles | Not needed | Not needed | As given; in an open workspace, their default-workspace role, at most Maintainer | As given; in an open workspace, their default-workspace role, at most Maintainer | None: refused until they are made a member |
| People, workspaces, policy, integrations, keys, agents, apps, domains, the audit | Yes | Yes | No | No | No |
| Buy a plan, the billing portal | Yes | Yes | Yes | No | No |
| The spending limit | Yes | Yes | No | No | No |
| Make or remove owners | Yes; the last owner can't step down | No | No | No | No |
| Delete the organization | Yes | No | No | No | No |
| Told of the organization's events | Yes | Yes | Only about instructions they read | Only about instructions they read | Only about what is shared with them |
An invitation gives one of admin, billing, member, guest. Owners are made with orgs_members_update, by an owner. A guest made a member takes a seat, and the plan's seat limit applies; see Rate and size limits. People join by invitation and accepting it; orgs_members_add adds agents.
Principals
| Principal | Id | How it gets a permission | Its limits |
|---|---|---|---|
| A person | usr_… |
Every source above | Their token's scopes; manage at most |
| An agent | agt_…, kind: agent |
A workspace role or a grant | publish at most, Maintainer at most in a workspace; the policy on agents; never the organization's admin tools |
| A service | agt_…, kind: service |
The same as an agent | The same as an agent |
| An organization | org_… in a grant |
A grant gives every one of its members (its guests too) that permission on one instruction | As each member's own limits |
| An app | its client | What the person who connected it chose | read at most; never the draft |
| Anyone signed out | none | Public instructions, on the web | read; over MCP every caller signs in |
Share one instruction
instructions_access_set gives people (by handle, email or id), agents or a whole organization a permission on one instruction, or none to take it away. The grants you don't name stay. Widening access asks for confirmation. It needs manage on the instruction.
{
"name": "instructions_access_set",
"arguments": {
"instructionId": "acme/support-agent",
"grants": [
{ "handle": "maria", "permission": "publish" },
{ "principalType": "agent", "principalId": "agt_01JX7Q4B8C2D6E0F3G7H1J5K9M", "permission": "edit" },
{ "principalType": "org", "principalId": "org_01JX9D5E7F9G1H3J5K7M9N1P3Q", "permission": "read" }
],
"workspaceBaseline": true
}
} The editor gives people read, suggest, publish or manage; edit is for agents. An agent is never given manage: "agents hold at most publish; they never manage". workspaceBaseline: false makes the workspace's roles give nothing on this instruction, so only its grants and the organization's owners and admins reach it. How sharing looks in the editor is on People and roles.
Legal hold
A legal hold keeps an organization's content from being destroyed while it holds. It is set on a whole organization or on one instruction by instruction.md's operators, in the database: no tool sets or lifts it. To ask about one, write to Support. orgs_get shows the organization's legalHold to its owners and admins.
While a hold is on, these are refused or skipped:
| What | Under hold |
|---|---|
instructions_purge (delete for good) |
Refused: "this instruction is under legal hold and can't be deleted" |
| The trash emptied after 30 days | Skipped: the instruction stays in the trash |
instructions_transfer to another organization |
Refused: "it is under legal hold and can't leave its organization" |
orgs_workspaces_delete |
Refused when the organization is held or its trash holds a held instruction |
orgs_delete |
Refused: "this organization is under legal hold and can't be deleted" |
me_delete, for a person whose personal organization holds held content |
Refused: "your account holds content under legal hold; it can't be deleted now" |
| The read log's retention | Skipped: no read of a held organization is removed |
A hold doesn't stop work. Editing, releasing, sharing, archiving and moving to the trash go on as before, and every change is recorded as always. What the audit trail keeps, and for how long, is on Audit trail.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
orgs_policy_get and orgs_policy_set aren't listed |
The token lacks org:admin, or it is an agent's |
Sign in as a person with org:admin: instruction login --admin, or add the scope to your host's connector. |
forbidden: "this needs an organization admin" |
You are a member or a billing member | Ask an owner or admin. |
validation naming a key |
A key the policy doesn't have | Use a key from Policy keys. |
validation: "memberRole: none, reader, contributor or maintainer" |
A value of another type or another word | Send one of the values the message lists. |
limit_reached: "restricting instructions to integrations needs the Team plan or above" |
integrationsOnly: true on a plan without it |
Upgrade (details.upgrade), or leave it off. |
An agent gets forbidden: "this organization doesn't let agents release versions (policy agentPublish) …" |
agentPublish is off |
Turn it on, or let the agent suggest and a person release. |
An agent gets forbidden: "agents can't widen who reads an instruction here …" |
agentSharing is off |
Turn it on, or have a person share. |
forbidden: "this needs manage on the instruction; you have publish" |
Sharing, renaming or deleting takes Admin | Ask an Admin of the instruction, or an owner or admin of the organization. |
| Still stuck | Ask on Support. |
Questions
What can a Reader, a Contributor, a Maintainer and an Admin do?
A Reader reads; a Contributor also comments and suggests; a Maintainer also edits, accepts suggestions, releases and moves refs; an Admin also shares, renames, archives and deletes. The full list is in Permissions and workspace roles, and in plain words on People and roles.
How do I stop agents from publishing on their own?
Leave agentPublish and aiAutoPublish off, as they are by default. Agents then suggest changes, and a person releases them. See Policy keys.
Who can turn the assistant off?
An owner or admin of the organization, with assistant: false or Settings ▸ Security ▸ The assistant in the editor. It is then off for everyone on the organization's instructions. See Policy keys.
Do guests count as seats, and what can they see?
No, guests take no seat. They see only what is shared with them, never what is visible to Your organization, and they hold no workspace role. See Organization roles.
Does requireSignedVersions refuse unsigned versions?
No. The key is stored and shown, and nothing checks it. On instruction.md every version is signed with the organization's key when it is released; a self-hosted server signs only when it has a signing key set up. To make a ref take only signed versions, set its requireSignature gate. See Signing and verification.
Generated from the code
The policy keys, their types and descriptions are orgs_policy_set's schema in packages/registry/registry.json, and their defaults are imd.policy_defaults in db/functions/70_org.sql. The ladder, the workspace roles' permissions and the roles errors name are imd.rank, imd.ws_perm and imd.role_of in db/functions/00_core.sql; the confirmation wording is imd.perm_label in db/functions/50_share.sql. The role names and what the editor says of them are the editor's catalogue. A key, a permission or a role the page doesn't describe stops the docs build.