Permissions

Document access is controlled through ACTOR events — an event-driven permission model. See Event Specification for the full event category reference.

Base rules

• The creator integration starts with write capabilities on created documents.
• Every document includes a system-level ACTOR automatically so platform services can read and create events when required.
• Additional participants and roles can be granted through ACTOR events.
• The most recent ACTOR permissions for a participant are the effective permissions ("last write wins").

Permission structure

Each policy is keyed by participantId and defines an effect (ALLOW / DENY), the actions it covers, and an optional condition.

Typical allow policy:

{
  "f56ed1cf-bfef-4299-8088-449a5d405130": [
    {
      "effect": "ALLOW",
      "actions": ["WRITE", "READ"],
      "condition": {
        "$in": {
          "eventNames": ["RELATED"]
        }
      }
    }
  ]
}

Typical deny policy:

{
  "f56ed1cf-bfef-4299-8088-449a5d405130": [
    {
      "effect": "DENY",
      "actions": ["WRITE"]
    }
  ]
}

If condition is omitted, the policy applies to the whole document context.

Recommended implementation pattern

1. Create document.
2. Add participant role events in explicit order.
3. Validate resulting access behavior in your integration tests.
4. Send an empty permissions array in ACTOR to remove participant access when needed.

Cross-integrator scenarios

To relate a document or add events in a document owned by another integration, an existing participant with access must add your participant as ACTOR with WRITE permission on that document.

Common pitfalls

• Sending duplicate/conflicting ACTOR updates without deterministic ordering.
• Assuming implicit access for participants not explicitly modeled.
• Mixing test/prod credentials in cross-party permission flows.

Reference: Events API.