Skip to content
Developer docs
Docs menu

Permissions

Markdown

How principals, capabilities, Space roles, read and write roots, and API key limits together decide a request.

How a request is decided

A request must satisfy all of these. Failing any one is a refusal:

text
allowed = capability in (principal.capabilities ∩ key.capabilities)
        and space in key.allowed_space_ids   (when set)
        and the Space role is sufficient
        and the path is under the member's read_root / write_root   (when set)

Principals

TypeNotes
Humankind: human, and may carry the tenant_admin role
Agentkind: agent, with its own permissions, memory, and audit identity
API keyA credential, not a principal; it can only narrow its principal

Principals have no display name, so keep your own label against id. POST /v2/principals creates human and agent principals, and the tenant_admin role cannot be granted through the API.

Capabilities

A capability is permission for one kind of operation, such as knowledge:read, knowledge:write, knowledge:manage, knowledge:answer, or memory:confirm. A key's effective capabilities are its principal's intersected with the key's own. effective_capabilities on GET /v2/whoami reports that intersection.

For what each capability allows, see DevCapability in the reference; each operation in the reference names the capability it needs.

Space roles

A member has one role in each Space: owner, editor, or viewer. An operation needs both a capability and a minimum role. What each role can do is in DevSpaceRole; the capability each operation needs, and any stricter rule, are in that operation's description in the API reference.

The Space owner sets a member's role, write_mode, write_root, and read_root with PUT /v2/spaces/{space_id}/members/{principal_id}.

Agent write mode

write_mode applies only to Agents, and only to files they do not own. A new member defaults to proposal: changing someone else's file returns 403 proposal_required, moves and deletes included, and creates nothing. Set it to direct to allow the write. The Space owner is always direct.

An Agent in proposal mode can send Prefer: handling=proposal to turn such a write into a proposal for a reviewer to approve. See Proposals.

Write roots and read roots

The Space owner can limit a member to one subtree when setting the membership. Both roots only narrow: role, capabilities, and API key limits still apply, and there are no deny rules. For the accepted values, see write_root and read_root.

curl
# The Agent reads /projects/acme and writes only under /projects/acme/drafts.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$AGENT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "editor", "write_mode": "direct",
       "read_root": "/projects/acme", "write_root": "/projects/acme/drafts"}'
RootInsideOutside
write_rootWrites below the directory, but not renaming, moving, or deleting the directory itself403 outside_write_root; reads are unaffected
read_rootReads the directory and everything under it, and writes there when there is no write_root404, the same as missing; search, context, memories, and the change feed leave it out
  • Entries without a path, such as ingest, project memories, and distilled facts, are outside both roots, except the member's own Agent memories.
  • A root follows its directory through renames and moves. Deleting a directory that is, or contains, a member's root returns 409 directory_is_write_root or directory_is_read_root, for the Space owner too.
  • A write_root does not limit branches; a merge into main is checked path by path, all or nothing.
  • GET /v2/spaces and GET /v2/spaces/{space_id} show your own read_root and write_root; start the tree there.

Set up an Agent

Give an Agent its own principal rather than sharing a person's API key. Its writes, memory, and audit trail then have their own identity, and revoking it affects no one else.

curl
# 1. Create the Agent. Without grant_capabilities it gets knowledge:read.
curl -X POST https://api.mirabase.dev/v2/principals \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "agent", "grant_capabilities": ["knowledge:read", "knowledge:write"]}'

# 2. Make it a member of one Space. write_mode direct lets it change files it does not own.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$AGENT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "editor", "write_mode": "direct"}'

# 3. Issue its key, narrowed to that Space.
curl -X POST https://api.mirabase.dev/v2/api-keys \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor_id": "'$AGENT_ID'", "name": "docs-agent",
       "grant_capabilities": ["knowledge:read", "knowledge:write"],
       "allowed_space_ids": ["'$SPACE_ID'"]}'

Limit a key to Spaces

  • Reaching a Space outside the list returns 404, the same as for a Space that does not exist.
  • A restricted API key cannot reach account-level or tenant-level surfaces: account memory, GET /v2/principals, GET /v2/api-keys, and GET /v2/audit/events.
  • A key narrower than its principal can issue keys only for that principal, so changing identity does not bypass a limit.

Invisible means not found

A resource you cannot see and one that does not exist both return 404. After a 403, read GET /v2/whoami. After a 404, check the id, the API key's Spaces, and your membership.

Audit

GET /v2/audit/events returns governance and access events. Events hold identifiers only, never user content. The service records a governance action in the same transaction as the change it makes, and rolls them back together.

Permission changes take effect on the next statement and so does revocation. There is no cache window.

Next steps