Skip to main content

​
About Rootly

Rootly is an incident management platform covering incidents, alerts, on-call schedules, escalation policies, retrospectives, and status pages. Serval connects to Rootly with an API key that you generate in Rootly and paste into Serval. Workflows then call the Rootly API on demand, with Serval attaching your stored key to every request automatically. Authentication: API key (sent as a Bearer token on every request to the Rootly API). Data sync: On demand only. There is no background sync, no resource ingestion, and no prebuilt workflows are installed with this integration - all reads and writes happen when a workflow runs.

​
What the Rootly integration enables

Anything defined in the Rootly API can be accessed through Serval.

​
Get your credentials

You need a Rootly API key. Rootly offers three key types, and Serval inherits whatever the key can do - pick the narrowest type that covers what your workflows touch:
  • Global API Key - org-wide; assigned the On-Call and Incident Response role at generation.
  • Team API Key - Team Admin permissions over that team’s entities, such as Schedules and Escalation Policies.
  • Personal API Key - inherits the permissions of the user who creates it.
Full details are in the Rootly API reference.
1

Open Organization Settings

Sign in to Rootly, click the Organization dropdown in the top navigation, and select Organization Settings.
2

Go to API Keys

Navigate to API Keys in the settings menu.
3

Generate a new key

Click Generate New API Key and select the API Key Type (Global, Team, or Personal) that matches your integration needs.
4

Name and create the key

Give the key a descriptive name, e.g. “Serval Production Integration”, and generate it.
5

Copy the token immediately

Copy the token value right away - Rootly shows it only once.
Rootly displays the API key a single time at creation. If you navigate away without copying it, you will need to generate a new key.
The key inherits the permissions of its type. If your workflows only touch one team’s schedules and escalation policies, a Team API Key is enough; reserve Global keys for org-wide automation.

​
Connect in Serval

1

Add the Rootly integration

In Serval, open the integrations page and choose Rootly to open the connect form.
2

Instance Name (optional)

Optionally fill in Instance Name (optional) - “A name to distinguish between different Rootly instances (e.g., ‘Production Rootly’)”. If you leave it blank, the connection is named “Rootly”.
3

API Key (required)

Fill in API Key - “Your Rootly API key. Generate this in Organization Settings > API Keys”. This is a password-style field; after saving, Serval shows it masked, with only the last 4 characters visible.
4

Save

Submit the form. Serval does not test the key against Rootly at save time, so a mistyped key is accepted here. If the save itself fails you will see a general error such as “Failed to connect service” or “Failed to install integration” - check your input and try again.
When you edit an existing connection, the API Key shows as a read-only masked value (bullet characters plus the last 4 characters of your key) with a control to replace it. Leaving it untouched - or starting a replacement and submitting nothing - keeps the stored key; only a non-empty new value replaces it. The Instance Name field comes pre-filled with the current name: type a new name to rename the connection, but note that clearing the field and saving keeps the existing name rather than blanking it.

​
Verifying the connection

The Rootly integration has no automated health checks in Serval, and the key is not validated when you save, so there is no pass/fail status to look for. To verify the connection:
  1. Create or run a simple workflow that reads Rootly data - for example, one that lists incidents or schedules.
  2. If the workflow returns Rootly data, the key works.
  3. If it fails with an authentication error, the key was likely revoked in Rootly or pasted incorrectly - generate a fresh key and update the connection.
A successful read only proves the key is valid - it does not prove the key can reach every resource. If a basic read works but a workflow gets a permission error on a specific resource (for example, another team’s schedules), the key’s type or owner lacks access in Rootly. See “Key permissions are inherited” below.

​
Gotchas and troubleshooting

Rootly has no health checks in Serval and the key is not checked at connect time, so a mistyped or revoked key is not caught when you save - it surfaces the first time a workflow calls the Rootly API. Generate a new key in Rootly, enter it in the connection settings, and re-run the workflow.
Serval does not add or remove any permissions - the connection can do exactly what the key can do in Rootly. A Global key carries the On-Call and Incident Response role org-wide, a Team key has Team Admin rights over that team’s entities, and a Personal key mirrors its creator. If a workflow gets a 403 on a specific resource, regenerate the key under an account or key type with the needed scope and update the connection.
Requests to Rootly are sent and received in the JSON:API format rather than plain JSON. Data you send when creating or updating records must be structured as a JSON:API document, and results come back wrapped in a “data” object containing an id, a type, and the record’s attributes. Workflow builders who expect flat JSON will find the fields one level deeper than anticipated.
Rootly list responses come back in pages, controlled by page number and page size parameters. To retrieve everything, workflows request page 1, then page 2, and so on until a page comes back with an empty data array.
Serval attaches your API key only to requests addressed to api.rootly.com, and requests to any other host are rejected. If a workflow request fails before reaching Rootly, check that it targets the Rootly API rather than another URL.
Rootly has no per-customer subdomains, so every connection points at the same Rootly service. If you connect more than one Rootly organization or key, set a distinct Instance Name on each - otherwise they all display as “Rootly” and are hard to tell apart in the UI.
Serval keeps using the stored key until it stops working. If you revoke or rotate the key in Rootly, workflows will start failing until you paste the new key into the connection. When rotating, edit the connection, replace the API Key with the new value, and save - the Instance Name can stay as is.
Need help? Contact support@serval.com for assistance with your Rootly integration.