Cette page n’est pas encore traduite.

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.

KeyTypeDefaultEffectIn 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
agentPublishbooleanfalseAgents 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
agentSharingbooleanfalseAgents 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
aiAutoPublishboolean | string[]falseAgents 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
requireSignedVersionsbooleanfalseStored 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
integrationsOnlybooleanfalseInstructions' 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
developerModebooleanfalseDeveloper 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
workspacePeoplebooleantrueThe 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
assistantbooleantrueThe 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.

tools/call params
{
  "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:

Turn 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:

Answer
{
  "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"
}
Put one key back, set another
{
  "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:admin scope. 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: true on a plan without the feature is limit_reached.
  • Recorded. A change that changes something records an org.updated event, its subject.keys naming 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.

  1. Visibility. A public instruction gives read to everyone. One visible to Your organization gives read to the organization's owners, admins, billing members and members, never its guests.
  2. Organization role. The organization's owners and admins have manage on every one of its instructions, in every workspace.
  3. 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).
  4. Grants. What instructions_access_set gave the person, the agent, or an organization they are a member of.

Then the limits:

  • Agents and services hold publish at most, whatever they are given.
  • A token holds at most what its scopes allow: instructions:read reads, instructions:write edits, instructions:publish publishes, instructions:admin manages. 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 read at most on this organization's instructions: anything above read becomes read on 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

PermissionWorkspace roleShown asConfirmation wordingAddsThe editor says
readReaderReaderCan readRead 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
suggestContributorContributorCan proposeComment, 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
editNone (granted only)MaintainerCan editEdit 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.
publishMaintainerMaintainerCan maintainAccept 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
manageAdminAdminCan manageShare (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 memberRole in the default workspace when nothing names another.

Organization roles

Owner (owner)Admin (admin)Billing (billing)Member (member)Guest (guest)
Takes a seatYesYesYesYesNo
The organization's instructionsAdmin (manage) on every one, in every workspaceAdmin (manage) on every one, in every workspaceRead those visible to Your organization; their workspace rolesRead those visible to Your organization; their workspace rolesOnly what is shared with them
Workspace rolesNot neededNot neededAs given; in an open workspace, their default-workspace role, at most MaintainerAs given; in an open workspace, their default-workspace role, at most MaintainerNone: refused until they are made a member
People, workspaces, policy, integrations, keys, agents, apps, domains, the auditYesYesNoNoNo
Buy a plan, the billing portalYesYesYesNoNo
The spending limitYesYesNoNoNo
Make or remove ownersYes; the last owner can't step downNoNoNoNo
Delete the organizationYesNoNoNoNo
Told of the organization's eventsYesYesOnly about instructions they readOnly about instructions they readOnly 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.

A person, an agent and a partner organization
{
  "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.

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.

Last checked against the product:

Was this page helpful? Report a problem