The Access Management plugin's API
All under /api/v1/x/access/, 404 while the plugin is off. Everything but the reviews is for admins (access:read;
changes access:admin). Reviews: admins see and start them; anyone sees and decides the items they review
(access:review). Guide: Access Management.
| Endpoint | What |
|---|---|
GET history?userId=&objectId=&kind=&action=&from=&to=&before=&limit= | The access history, newest first: { events, next } (before=<next> for the next page). kind: unit, admin, account, or a plugin's (project); action: granted, revoked, role_changed, disabled, enabled. |
GET history.csv?… | The same as CSV (UTF-8 with a BOM, up to 50,000 rows). |
GET who?kind=unit|case|project&id= | Who can see it, and why (via), for a unit id, a case reference or a plugin's thing. |
GET things | The plugins' kinds and their things (from AccessProvider.list). |
GET people/<userId> | What a person can see: admin, units placed in (and how many below), plugins' things with role and how, API tokens (no secrets), recent changes. |
GET alerts, POST alerts/seen | Alerts with how many are unseen; { ids } or { ids: "all" } marks them seen. |
GET audit?actorId=&target=&action=&q=&from=&to=&before=&limit=, GET audit.csv?… | Search the audit log (action is a prefix), with whether each entry is sealed; CSV up to 100,000 rows (the export is audited as access.audit.exported). |
POST audit/verify | Seal what isn't yet, then check every seal: { sealed, intact, problems: [{ seq, auditId, at, problem: 'changed' | 'removed' }], pruned, unsealed }. |
GET settings, PATCH settings | alertUserIds, alertOnGrant, alertOnAdmin, alertManyPeople, retention ([{ prefix, days }], at least 30 days), remindDays. |
GET reviews, GET reviews/count | Reviews (all for admins, yours otherwise); for the sidebar { pending, alerts }. |
POST reviews | Admins: { name, description, dueAt, scope: { units: true | [unitIds], admins, kinds: ['project'] }, reviewerIds }. |
GET reviews/<id>, PATCH reviews/<id>/items | A review with its items (yours unless admin); { items: [{ id, decision: 'keep' | 'remove' | null, note }] }. A removal is carried out where possible (applied, appliedNote); one carried out can't be undone here (409 applied). |
POST reviews/<id>/close, GET reviews/<id>/export.csv | Admins: close (final; 409 after), and the evidence as CSV. |
The plugin listens to the desk's staff events (units_changed, role_changed, disabled, enabled,
unit_deleted) and every plugin's ctx.access.changed. It reads plugins' access through their providers, and removes
by-name access with the provider's optional revoke(objectId, userId, actorId) (and lists things with list() for
reviews).
| Job | Runs |
|---|---|
plugin.access.seal | Every minute. |
plugin.access.reminders | Hourly. |
plugin.access.retention | Nightly. |
MCP tools
| Scope | Tools |
|---|---|
access:review | list_access_reviews, get_access_review, decide_access_review |
access:read (admins) | access_history, who_can_see, what_can_person_see, search_audit_log, verify_audit_seal, list_access_alerts |
access:admin (admins) | start_access_review |
Webhook events
| Event | With |
|---|---|
access.granted, access.revoked | event: action, kind, plugin, object, person, source, role, by, reason. |
access.alert | |
access.review_started | |
access.review_closed | kept, removed, pending. |
access.seal_broken |
Audited: settings, audit exports, starting, closing and exporting reviews, removals made by a review.