Permissions
MarkdownHow 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:
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
| Type | Notes |
|---|---|
| Human | kind: human, and may carry the tenant_admin role |
| Agent | kind: agent, with its own permissions, memory, and audit identity |
| API key | A 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.
# 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"}'| Root | Inside | Outside |
|---|---|---|
write_root | Writes below the directory, but not renaming, moving, or deleting the directory itself | 403 outside_write_root; reads are unaffected |
read_root | Reads the directory and everything under it, and writes there when there is no write_root | 404, 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_rootordirectory_is_read_root, for the Space owner too. - A
write_rootdoes not limit branches; a merge into main is checked path by path, all or nothing. GET /v2/spacesandGET /v2/spaces/{space_id}show your ownread_rootandwrite_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.
# 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, andGET /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.
Next steps
- Authentication and API keys: create, rotate, and revoke keys.
- Files and versions: submit and review proposals.
- Error codes: what each 403 code means.
