# Permissions

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

| 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`](https://mirabase.io/developers/api/principals.md#principals-create) 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`](https://mirabase.io/developers/api/identity.md#identity-whoami) reports that intersection.

For what each capability allows, see [DevCapability](https://mirabase.io/developers/api/schemas.md#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](https://mirabase.io/developers/api/schemas.md#DevSpaceRole); the capability each operation needs, and any stricter rule, are in that operation's description in the [API reference](https://mirabase.io/developers/api.md).

The Space owner sets a member's role, `write_mode`, `write_root`, and `read_root` with [`PUT /v2/spaces/{space_id}/members/{principal_id}`](https://mirabase.io/developers/api/spaces.md#spaces-setmember).

## 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](https://mirabase.io/developers/files.md#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](https://mirabase.io/developers/api/spaces.md#spaces-setmember.body.write_root) and [read_root](https://mirabase.io/developers/api/spaces.md#spaces-setmember.body.read_root).

curl:

```bash
# 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"}'
```

TypeScript:

```ts
await mirabase.spaces.members.set(agentId, {
  role: "editor",
  write_mode: "direct",
  read_root: "/projects/acme",
  write_root: "/projects/acme/drafts",
});
```

Python:

```python
# agent_id is the Agent's principal id. It reads /projects/acme and writes only under /projects/acme/drafts.
mb.spaces.members.set(agent_id, {
    "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_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`](https://mirabase.io/developers/api/spaces.md#spaces-list) and [`GET /v2/spaces/{space_id}`](https://mirabase.io/developers/api/spaces.md#spaces-read) 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.

```bash
# 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`](https://mirabase.io/developers/api/principals.md#principals-list), [`GET /v2/api-keys`](https://mirabase.io/developers/api/api-keys.md#apikeys-list), and [`GET /v2/audit/events`](https://mirabase.io/developers/api/audit.md#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`](https://mirabase.io/developers/api/identity.md#identity-whoami). After a 404, check the id, the API key's Spaces, and your membership.

## Audit

[`GET /v2/audit/events`](https://mirabase.io/developers/api/audit.md#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.

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

## Next steps

- [Authentication and API keys](https://mirabase.io/developers/authentication.md): create, rotate, and revoke keys.
- [Files and versions](https://mirabase.io/developers/files.md#proposals): submit and review proposals.
- [Error codes](https://mirabase.io/developers/errors.md#codes): what each 403 code means.
