Admin monitoring

Two surfaces expose the write-only alert sinks that were previously only visible in tests. Team owners can also resolve or dismiss their own alerts and track which ones they have read; the platform admin surface is read-only.

Team admin alerts

Team owners can list unresolved operational alerts for their team, resolve or dismiss them, and mark them read. These carry diagnostic payloads — every team alert route is JWT-only and cannot be used with a mio_sk_ API key.

GET /api/v1/teams/{team_id}/admin-alerts

Auth: team-owner JWT session. API keys are rejected. Query parameters:

Parameter	Default	Notes
`filter[status]`	`open`	Only `open` is accepted in v1. Any other value returns `422`.
`page[size]`	`50`	1–100.
`page[after]`	—	Cursor from the previous page’s `links.next`.

Response shape:

{
  "data": [
    {
      "id": "0197...",
      "type": "admin_alerts",
      "attributes": {
        "source_module": "checkout",
        "alert_type": "stripe_sync_drift",
        "hub_id": "hub_abc",
        "payload": { "order_id": "ord_123", "gap_seconds": 420 },
        "created_at": "2026-06-09T14:00:00Z",
        "status": "open",
        "read": false,
        "resolved_at": null,
        "resolved_by": null
      }
    }
  ],
  "meta": { "page": { "size": 50, "has_more": false, "next_cursor": null }, "unread_count": 1 }
}

Results are ordered most-recent first. The list returns unresolved alerts only. read is your own read marker, never another user’s. meta.unread_count is how many of the team’s open alerts you have not read, across the whole list rather than just the current page.

Resolve, dismiss or mark read

PATCH /api/v1/teams/{team_id}/admin-alerts/{alert_id}

{
  "data": {
    "type": "admin_alerts",
    "attributes": { "status": "resolved", "read": true }
  }
}

Send at least one attribute:

Attribute	Values	Effect
`status`	`resolved` or `dismissed`	Closes the alert. This only records the outcome (`status`, `resolved_at`, `resolved_by`); nothing is retried or replayed. A closed alert leaves the open list and the unread count.
`read`	`true` or `false`	Sets your own read marker. It works on open and closed alerts and never affects anyone else.

data.id is optional; if you send it, it must match the alert in the URL (otherwise 409 resource_id_mismatch). The response is the alert with its new status and read, plus meta.unread_count.

Repeating a request is safe. Sending the same status again returns 200 and keeps the original resolved_at and resolved_by.
A closed alert cannot be closed the other way. Asking for dismissed on a resolved alert (or the reverse) returns 409 alert_already_closed.
404 — the alert does not exist, is not a valid alert id, or belongs to another team. These cases are indistinguishable by design.
403 — the caller is not the team owner, or used an API key.
422 — an unknown attribute, an empty attributes object, a null value, or a status other than resolved or dismissed.

Platform admin alerts

Platform admins can list unresolved cross-tenant alerts (abuse signals, infrastructure events).

GET /api/v1/admin/platform-alerts

Auth: platform_admin role required. Query parameters:

Parameter	Default	Notes
`filter[status]`	`open`	Only `open` is accepted in v1.
`filter[severity]`	—	One of `info`, `warning`, or `critical`. Omit to return all severities. Any other value returns `422`.
`page[size]`	`50`	1–100.
`page[after]`	—	Pagination cursor.

Response shape:

{
  "data": [
    {
      "id": "0197...",
      "type": "platform_alerts",
      "attributes": {
        "alert_type": "rate_limit_surge",
        "severity": "warning",
        "payload": { "ip": "198.51.100.1", "route": "/api/v1/hub/{hub_id}/checkout" },
        "created_at": "2026-06-09T15:00:00Z",
        "resolved_at": null,
        "resolved_by": null
      }
    }
  ],
  "meta": { "has_more": false }
}

Results are ordered most-recent first.

Role permissions

Platform admins can assign and remove permissions from roles without rebuilding the role.

POST   /api/v1/roles/{role_id}/permissions
DELETE /api/v1/roles/{role_id}/permissions/{permission_slug}

Auth: JWT session. API keys are rejected.

Assign a permission

curl -X POST "$MIO_BASE_URL/api/v1/roles/$ROLE_ID/permissions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"slug": "content:read"}'

Returns 201 with the updated role resource. Re-assigning a permission the role already holds is a no-op that still returns 201.

Remove a permission

curl -X DELETE "$MIO_BASE_URL/api/v1/roles/$ROLE_ID/permissions/content:read" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content. Removing a permission the role does not hold is a no-op that still returns 204. Returns 404 if the role itself does not exist.

Conventions

Endpoints

Appendix

Team admin alerts

Resolve, dismiss or mark read

Platform admin alerts

Role permissions

Assign a permission

Remove a permission

​Team admin alerts

​Resolve, dismiss or mark read

​Platform admin alerts

​Role permissions

​Assign a permission

​Remove a permission

Team admin alerts

Resolve, dismiss or mark read

Platform admin alerts

Role permissions

Assign a permission

Remove a permission