Skip to main content

​
Overview

Subscribers can be managed through the API as well as through the Web interface and Slack. Use it to grant access from a script or an internal tool — onboarding a security reviewer onto every SEV0, for instance, without a human clicking through a dialog.
The subscriber list is an access control list for private incidents.On a private incident, adding a user as a subscriber grants them read access to that incident — its details, timeline, roles, and integrations — even when their role carries no private incident permission at all.Removing them takes away the access the subscription granted. Access is additive: a user whose role already carries private incident read permission, or who holds an incident role that cascades it, keeps that access after you remove them as a subscriber.A script that adds subscribers is a script that grants access. Treat the user_ids it sends with the same care as any other permission change.
Private incident access is additive: a user can see a private incident if their role grants private incident read access, or if they are on that incident’s subscriber list. See Private Incidents for how the two interact.

​
Subscribers You Did Not Add

The subscriber list does not only contain people someone added deliberately. Rootly subscribes users automatically in several situations, and because subscription grants read access on a private incident, each of these is also an access grant. Automatically subscribed:
  • The incident’s creator.
  • Anyone assigned an incident role.
  • Users on a team attached to the incident.
  • Owners of an attached service or functionality.
  • Responders on an alert attached to the incident.
  • Anyone who joins the incident’s Slack channel. Leaving the channel unsubscribes them again.
This is not only a declaration-time sweep. Attaching a team, service, or functionality to an incident later subscribes that group’s users then — so the list grows as the incident’s scope grows, which is usually what you want and occasionally is not.
Joining the Slack channel subscribes you. On a private incident that means Slack channel membership is a route to read access — someone invited to the channel to answer one question is subscribed, and a subscriber can read the incident.Audit the Slack channel, not just the subscriber list, when an incident is genuinely sensitive. They are the same list from two directions, and the Slack side is the one people change casually.A subscriber does not have to hold a Rootly account. Someone present in the incident’s Slack channel is recorded as a subscriber against their Slack identity, so the subscriber list is not the same as your user list. Adding someone deliberately, through the web Manage Access dialog or the API’s user_ids, still takes a Rootly user.
Review the subscriber list before treating an incident as closely held, and use remove_users_with_no_private_incident_access below to sweep anyone who should not be there.

​
Adding Subscribers

POST /v1/incidents/{id}/add_subscribers
​
array of user IDs
The users to add to the incident’s subscriber list.
​
boolean
default:"false"
When true, users who lack role-based read permission for private incidents are removed from the subscriber list.

​
Removing Subscribers

DELETE /v1/incidents/{id}/remove_subscribers
Note the verb: adding is a POST, removing is a DELETE that carries a body. Removing a subscriber from a private incident revokes the access that subscription granted — not any access they hold through their role. If Slack permissions allow, they are also removed from the incident’s Slack channel — see Manage Access via Slack for the cases where Slack rejects the removal.
Paths, headers, and request shapes on this page are reproduced for convenience. The generated API Reference is the source of truth — if the two ever disagree, believe the reference.

​
Sweeping Unauthorized Subscribers

Both endpoints accept remove_users_with_no_private_incident_access. Set to true, it strips every subscriber who does not independently hold role-based private incident read permission.
The sweep runs after the add, in the same request. If you send user_ids and remove_users_with_no_private_incident_access: true together, anyone in that list without role-based access is added and then immediately removed again — the call succeeds and the person you meant to grant access to is not a subscriber.Send them as two requests: add first, then sweep. Or leave the flag off when you are adding people deliberately, which is the more common intent.
This is the control for an incident that has become private after people were already subscribed, or one where an investigation has narrowed and the participant list should narrow with it.
This removes people, and it removes them by permission rather than by name. Anyone who was subscribed specifically because they lacked the role — an external reviewer, a support lead, a legal contact invited onto this one incident — is exactly who it takes out.Read the current subscriber list before running it, and re-add anyone whose access was deliberate.

Private Incidents

How role-based and subscriber-based access combine to control who sees a private incident.

Manage Access via Web

The same operations through the Manage Access dialog.

Manage Access via Slack

The same operations from the incident channel, including what happens when Slack rejects a removal.

API Reference

Generated request and response schemas — the source of truth for these endpoints.