> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rootly

> Connect a Rootly organization to Oleria to discover members, teams, Incident Response and On-Call roles, services, schedules, escalation policies, status pages, API keys and other non-human identities, and audit log activity, and take remediation actions directly from Oleria.

Rootly is an incident management and on-call platform. Connect a Rootly organization to Oleria to see who belongs to it, which teams they're in, which Incident Response and On-Call roles they hold, who owns your services, schedules, and escalation policies, which API keys and agents can act on the organization, and which webhook endpoints and secrets it holds. Oleria reads this data from the Rootly REST API with a Global API key. You can then review over-provisioned access and take action directly from Oleria.

One Oleria integration covers one Rootly organization. To connect another organization, add another integration.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Rootly organization:

* **Accounts** - every member of the organization, with name, email, time zone, and phone number. Each member's Incident Response role is shown as their account role, and their On-Call role as a secondary role.
  * **Administrators** - a member is marked as an administrator when either of their roles is the built-in **Owner** or **Admin** role, or a custom role that can create, update, or delete roles, On-Call roles, members, or invitations.
  * **API access** - a member is shown with API access when either of their roles can create API keys.
  * **Last activity** - the most recent change the member made in Rootly in the last 30 days, read from the audit log. This requires the Enterprise plan. See [Known limitations](#known-limitations).
* **Teams** - every team appears as a group, with its members. Team admins are shown as managers of the team. Teams synced from your identity provider over SCIM are shown as synced groups.
* **Roles** - both of Rootly's role families, and who holds each:

  * **Incident Response roles** - the built-in **Owner**, **Admin**, **User**, **Observer**, and **No Access** roles, and your custom roles.
  * **On-Call roles** - the built-in **Admin**, **User**, **Observer**, and **No Access** roles, and your custom roles. Oleria adds `(On-Call)` to their names, for example **Admin (On-Call)**, so you can tell the two families apart.

  Oleria shows what each role's permissions allow on services, functionalities, schedules, escalation policies, and status pages, and on the organization for every other area, such as incidents, workflows, and billing. Permission to create, update, or delete roles, On-Call roles, API keys, invitations, members, billing, or secrets is marked as privileged.
* **Resources** - the organization itself, services, functionalities, on-call schedules, escalation policies, status pages, and dashboards, with who has direct access to each:
  * The owning teams and owning users of services, functionalities, and schedules are shown with owner access, which covers viewing and editing.
  * The teams associated with an escalation policy are shown as its owners.
  * The teams on a status page are shown with their permission: edit and publish, or publish only.
  * Users and teams shared on a dashboard are shown with their access. A personal dashboard's owner is shown as its owner. Public dashboards are shown as readable by anyone.
* **Non-human identities (NHIs)**:

  * **API keys** - every API key in the organization, with its kind, expiry, last-used date, and the member who created it. A personal key is shown as a personal access token that acts as the member who created it. Global and team keys are shown as API tokens. Expired keys are shown as disabled.
  * **Service accounts** - Rootly creates a service account behind every Global and team key. Oleria shows it as a machine account that the key authenticates. A Global key's service account holds the Incident Response and On-Call roles chosen for the key. A team key's service account is shown as a member and manager of its teams.
  * **Webhook endpoints** - outgoing webhook endpoints, shown as HMAC keys with their signing secret, the events they receive, and the host they send to.
  * **Alert sources** - alert sources that have an ingestion secret. Each secret can only create alerts for its source.
  * **Heartbeats** - heartbeats that have a ping secret, with when each was last pinged.
  * **Secrets** - secrets stored in Rootly for workflows, including secrets that reference HashiCorp Vault. Secrets require the Enterprise plan.
  * **Private Agents** and **Edge Connectors** - the agents and connectors you run in your own network, with their status and when each last contacted Rootly.

  The owning teams of alert sources, heartbeats, secrets, and Edge Connectors are shown as their owners. Oleria never reads secret values, signing secrets, or key values, and keeps only the host of a webhook URL.
* **Activity** - events from the Rootly audit log, on the Enterprise plan, such as:

  * objects created, changed, or deleted
  * API key and secret changes
  * member role changes
  * team membership changes
  * browser IP policy changes

  Each event shows the member who made it, when Rootly names a current member, and the IP address and user agent. Changes to items Oleria doesn't inventory, such as incidents and workflows, are shown as changes to the Rootly organization. On the first sync, Oleria also imports earlier audit log events.

Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model).

> [!NOTE]
>
> Oleria doesn't import incidents, alerts, workflows, catalogs, or their settings.

## Prerequisites

* A Rootly organization. Activity, member last activity, stored secrets, and custom roles require the Rootly **Enterprise** plan.
* A Rootly **Owner** or **Admin** to generate a Global API key.
* Admin access to the Oleria workspace.

### Permissions

Rootly gives every member, and every Global API key, two roles: an Incident Response role and an On-Call role. Each role grants permissions by area, such as teams, roles, or API keys. Oleria names each permission after the role and area that grant it, in the form `role.<area>_permissions:<operation>` for the Incident Response role and `on_call_role.<area>_permissions:<operation>` for the On-Call role. The integration's **Capabilities** tab uses the same names.

We recommend the built-in **Admin** Incident Response role and the built-in **Admin** On-Call role. Together they grant every permission on this page, for discovery and for remediation actions.

If you use custom roles, they need these permissions for discovery:

| Permission | Used for |
| :- | :- |
| `on_call_role.members_permissions:read` | Members. Required. Rootly doesn't document which permission controls its member list, so Oleria checks this one. |
| `role.groups_permissions:read` | Teams. Required. |
| `role.roles_permissions:read` | Incident Response roles, and identifying your organization. Required. |
| `on_call_role.on_call_roles_permissions:read` | On-Call roles. Optional: without it, or if your plan has no On-Call, Oleria leaves On-Call roles and their members out of the sync. |
| `role.api_keys_permissions:read` | API keys and their service accounts. Required. |

Oleria also reads secrets, webhook endpoints, alert sources, heartbeats, services, functionalities, schedules, escalation policies, status pages and their teams, Private Agents, Edge Connectors, and the audit log. Each of these is optional. When Rootly withholds one, because of the key's roles or your plan, Oleria leaves it out and syncs the rest.

When you connect, Oleria refuses a key whose roles lack `role.groups_permissions:read`, `role.roles_permissions:read`, or `role.api_keys_permissions:read`. If the roles can't read members, the sync fails.

Remediation actions also need write permissions, listed for each action in [Remediation actions](#remediation-actions). Write permissions are required for actions only. A key without them can still connect and sync.

## Set up access in Rootly

**1. Open the API keys page**

Sign in to Rootly as an **Owner** or **Admin**. Open the organization dropdown and select **Organization Settings** -> **API Keys** -> **Generate New API Key**.

**2. Choose a Global key and its roles**

Choose the **Global** key kind. Set the key's Incident Response role to **Admin** and its On-Call role to **Admin**. If you use custom roles instead, they need the permissions in [Permissions](#permissions).

Don't use a personal key. A personal key acts as the member who created it and stops working when that member leaves the organization.

**3. Copy the key**

Generate the key and copy its value. Rootly keys expire at most five years after they're created, so note the expiry date and replace the key before then.

> [!NOTE]
>
> The Rootly interface changes over time. If these steps don't match what you see, refer to Rootly's [API documentation](https://docs.rootly.com/api-reference/overview).

## Connect Rootly to Oleria

**1. Open the integration**

Sign in to your Oleria workspace, navigate to **Integrations**, and select **Rootly**.

**2. Complete the connection form**

Fill in the connection form:

| Field | Notes |
| :- | :- |
| API key | Required. The Global API key you generated. |

**3. Authenticate**

Select **Authenticate**. Oleria checks that Rootly accepts the key and that the key's roles can read teams, roles, and API keys. If the key can't read On-Call roles, Oleria accepts the connection with a warning: On-Call roles and memberships will be left out of each sync. It then identifies your Rootly organization and saves the integration, named after your organization.

### Edit the connection

You can replace the **API key** of an existing integration, for example when you rotate it. Leave the field blank to keep the stored key. Oleria refuses a key from a different Rootly organization. To connect another organization, add a new integration.

## Verify the integration

Confirm the Rootly integration appears on the **Connected** tab of your Oleria **Integrations** page. After the first sync completes, check that members, teams, roles, resources, and NHIs appear in your Oleria workspace, and that members with the **Owner** or **Admin** role are marked as administrators.

## Remediation actions

Oleria runs actions with the integration's API key. Before every action, Oleria reads the key's Incident Response and On-Call roles and checks that they grant the permissions the action needs. If Oleria can't read the roles, the action doesn't run.

| Action | What it does | Revert |
| :- | :- | :- |
| Add user to group | Adds the member to a Rootly team. | Supported - removes the member from the team again. |
| Remove user from group | Removes the member from a team, including their team admin status. | Supported - adds the member back, as a team admin if they were one. |
| Add user to role | Sets the member's Incident Response or On-Call role to the selected role. Every member holds exactly one role of each kind, so this replaces their current role of that kind. | Supported - restores the previous role, unless the member's role has changed since. |
| Remove user from role | Moves the member to the built-in **No Access** role of the same kind. If the member doesn't hold the role, nothing changes. | Supported - restores the previous role, unless the member's role has changed since. |
| Delete user | Removes the member from the organization. Their personal API keys stop working. | Not supported - invite the person again in Rootly. |
| Create group | Creates a Rootly team with the name you enter. If a team with that name already exists, nothing changes. | Supported - deletes the team, unless it has members by then. |
| Revoke permission to resource | Deletes a status page's team assignment or a dashboard share. | Supported - re-creates the assignment or share. Refuses services, functionalities, schedules, and escalation policies, because access to them comes from ownership or roles. Also refuses a dashboard the user owns. |
| Revoke anonymous access to resource | Sets a status page or dashboard to private (`public=false`). | Supported - sets it back to public. |
| Disable NHI accounts | Revokes an API key, or turns off a webhook endpoint, alert source, Private Agent, or Edge Connector. See [Disable NHI accounts](#disable-nhi-accounts). | Depends on the NHI type. |

### Disable NHI accounts

| NHI | What Oleria does | Revert |
| :- | :- | :- |
| API key (personal access token or API token) | Revokes the key. Rootly deletes revoked keys. | Not supported - create a new key in Rootly. |
| Service account | Revokes the Global or team key behind it, which also deletes the service account. | Not supported - create a new key in Rootly. |
| Webhook endpoint (HMAC key) | Turns the endpoint off. | Supported - turns it back on. |
| Alert source (API token) | Turns the alert source off. | Supported - turns it back on. |
| Private Agent (application) | Pauses the agent. Oleria doesn't revoke Private Agents. | Supported - turns it back on. |
| Edge Connector (application) | Pauses the connector. | Supported - sets it back to active. |
| Heartbeat (API token) | Not supported. Rootly can't disable a heartbeat's ping secret without deleting the heartbeat. Delete it in Rootly instead. | - |
| Secret | Not supported. A Rootly secret has no disabled state, and deleting it breaks every workflow that reads it. Remove it in Rootly instead. | - |

### Required permissions

Each action needs these permissions. The write permissions among them are required for actions only.

| Action | Required permissions |
| :- | :- |
| Add user to group, Remove user from group | `on_call_role.members_permissions:read`, `role.groups_permissions:read`, `role.groups_permissions:update` |
| Add user to role, Remove user from role | `on_call_role.members_permissions:read`, `on_call_role.members_permissions:update`, `role.roles_permissions:read`, `on_call_role.on_call_roles_permissions:read` |
| Delete user | `on_call_role.members_permissions:read`, `on_call_role.members_permissions:delete`, `role.roles_permissions:read` |
| Create group | `role.groups_permissions:read`, `role.groups_permissions:create`, `role.groups_permissions:delete` |
| Revoke permission to resource | The built-in **Owner** or **Admin** Incident Response role, plus `on_call_role.members_permissions:read`, `role.groups_permissions:read`, `role.status_pages_permissions:read` |
| Revoke anonymous access to resource - status page | `role.status_pages_permissions:read`, `role.status_pages_permissions:update` |
| Revoke anonymous access to resource - dashboard | The built-in **Owner** or **Admin** Incident Response role |
| Disable NHI accounts - API key or service account | `role.api_keys_permissions:read`, `role.api_keys_permissions:delete` |
| Disable NHI accounts - webhook endpoint | `role.webhooks_permissions:update` |
| Disable NHI accounts - alert source | `on_call_role.alert_sources_permissions:update` |
| Disable NHI accounts - Private Agent | `role.private_agent_permissions:update` |
| Disable NHI accounts - Edge Connector | `role.edge_connector_permissions:update` |

Rootly reserves status-page team assignments and dashboard sharing for the built-in Owner and Admin Incident Response roles. A custom role can't run these actions.

**Create group** also needs `role.groups_permissions:delete`, so that Oleria can revert it. Oleria checks for it before it creates the team.

For **Disable NHI accounts**, the integration's **Capabilities** tab lists all six permissions, and shows the action as available when the key's roles have `role.api_keys_permissions:read` and `role.api_keys_permissions:delete`. Each disable checks only the permission for its own NHI type.

### Guardrails

Oleria refuses these actions and sends no change to Rootly:

* Changing the team membership or role of the user the integration's API key acts as, or deleting that user.
* Revoking any API key that belongs to the user or service account the integration's API key acts as. Rootly can't tell Oleria which key a request uses, so Oleria protects all of them.
* Changing the members of a team synced from your identity provider over SCIM. Change them in your identity provider instead.
* Granting the **Owner** role, changing an Owner's Incident Response role, or deleting an Owner.
* Removing the **No Access** role. Assign the member another role instead.
* Revoking a Global or team API key that was used in the last 24 hours, or whose last-used date Rootly doesn't return. Rootly can't say which key this integration authenticates with, so revoke it in Rootly.

Keep these points in mind:

* If the target is already in the requested state, the action succeeds without making a change, and there's nothing to revert.
* Oleria confirms every change by reading it back from Rootly.
* Rootly has no way to add or remove a single team member. To change a team's membership, Oleria reads the team and writes back its whole member and admin lists. A change someone makes to the same team in Rootly between Oleria's read and write can be lost.
* A revert acts only while the target is still in the state the action left it in. If someone changed it since, Oleria leaves it as it is and reports why.

## Known limitations

* **Activity and last activity require the Enterprise plan.** Rootly's audit log is available only on Enterprise. On other plans, or when the key's roles can't read the audit log, Oleria syncs no activity and members' last activity stays empty. The rest of the organization still syncs.
* **Last activity counts changes only, for 30 days.** Rootly has no last sign-in field and keeps sign-ins out of its audit log. Oleria uses the most recent change a member made in the last 30 days, so members who only view Rootly, or who made no change in that time, show no last activity.
* **MFA and SSO aren't available.** Rootly enforces MFA through your identity provider, and its API doesn't expose its SSO settings or how each member signs in. MFA and SSO show as unavailable for every member.
* **No password-change dates.** Rootly doesn't record when a member last changed their password.
* **Members can't be suspended.** Rootly has no disabled or suspended state, so every member is shown as enabled. **Delete user** is the only offboarding action, and it can't be reverted.
* **Members can't be invited.** Rootly's API has no invitation or user-creation endpoint, and pending invitations aren't shown.
* **Sessions can't be revoked.** Rootly has no API to end a member's sessions.
* **Seat types aren't known.** Rootly's API doesn't say which kind of seat a member holds.
* **Service accounts come from their keys.** Rootly doesn't list the service accounts it creates for Global and team keys. Oleria shows one for each key, and it disappears when the key is revoked. OAuth applications and their service users aren't shown, because Rootly's API doesn't list them.
* **API key revocation is permanent.** Rootly deletes a revoked key, so **Disable NHI accounts** can't be reverted for API keys and service accounts.
* **Heartbeat secrets and stored secrets can't be disabled from Oleria.** See [Disable NHI accounts](#disable-nhi-accounts).
* **Incident permission sets aren't shown.** Rootly can restrict a role inside incidents, for example by severity or incident type. Oleria shows each role's permissions, but not these restrictions.
* **Ownership may overstate edit access.** Oleria gives the owning teams and users of services, functionalities, and schedules view and edit access, and treats the teams associated with an escalation policy as its owners. Rootly may limit editing to team admins, and an escalation policy's teams may only be notified, so some team members can appear with more access than Rootly gives them.
* **Some events have no actor.** Rootly's audit log doesn't record which API key made a change. Events made by removed members, by Rootly staff, or with the service account behind a key show no actor.
* **No AI agents.** Rootly's AI SRE acts within the roles of the members who use it, and Rootly's API doesn't expose it, so Oleria shows no AI agents for Rootly.
* **Some behavior isn't confirmed on a live organization yet.** This integration was built from Rootly's API documentation. Discovery, activity, and remediation actions haven't been confirmed against a live Rootly organization. If something doesn't match what this page describes, contact us.

## Troubleshooting

| What you see | What to do |
| :- | :- |
| Rootly rejected the API key (`HTTP 401`) | The key is wrong, revoked, or expired. Generate a new Global key and enter it. |
| The API key's roles can't read the listed permissions | Generate a Global key with the **Admin** Incident Response role and the **Admin** On-Call role, or add the listed permissions to the key's custom roles. |
| The API key belongs to a different Rootly organization | You entered a key from another organization while editing the integration. Enter a key from the original organization, or add a new integration for the other one. |
| The sync fails | The key's roles must read members, teams, Incident Response roles, On-Call roles, and API keys. Check them against [Permissions](#permissions). |
| Secrets, activity, or other objects are missing | Rootly withholds what the key's roles can't read, and Enterprise features on other plans. Check your plan and the key's roles. |
| An action shows **Needs permission** on the **Capabilities** tab | Grant the missing permissions the tab lists for that action, then reconnect the integration. |

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.