> ## Documentation Index > Fetch the complete documentation index at: https://docs.serval.com/llms.txt > Use this file to discover all available pages before exploring further. # incident.io > Connect incident.io to Serval with an API key so workflows can read and manage incidents, alerts, escalations, on-call schedules, and everything else in the incident.io API. ## About incident.io incident.io is an incident management and on-call platform. Serval connects to it with a single API key - you paste it in once, Serval verifies it directly with incident.io, stores it securely, and attaches it to every request a workflow makes on your behalf. Serval identifies your incident.io organization automatically from the key, so there is nothing else to fill in. Serval only ever sends the key to one host for this integration: api.incident.io. **Authentication:** incident.io API key - a single key pasted into Serval. There is no OAuth or sign-in flow. **Data sync:** None. There is no background sync, no webhooks or triggers, and no ticket or asset ingestion - all data access happens on demand when a workflow runs, so results are always exactly as fresh as what incident.io returns at that moment. ## What the incident.io integration enables | Capability | Description | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Full incident.io API access | Workflows use the "incident.io API request" action to reach all 74 endpoint paths of the incident.io API: incidents (including creating and editing them), alerts, alert routes and sources, escalations and escalation paths, on-call schedules with entries and overrides, follow-ups, incident roles, statuses, types, timestamps, updates, attachments and relationships, custom fields, severities, users, incident.io workflows, catalog data, actions, and IP allowlists. | | Typed, checked requests | The action is generated from incident.io's published API specification, so request paths, parameters, and response shapes are checked while a workflow is being written - mistakes are caught before anything runs. | Anything defined in the [incident.io API](https://api-docs.incident.io/) can be accessed through Serval. ## Get your credentials Serval needs an incident.io API key. Keys in incident.io are created with a specific set of permissions, and Serval can only do what the key allows - so create the key with permissions covering everything your workflows will do. incident.io's API documentation lives at [api-docs.incident.io](https://api-docs.incident.io/). Log in to your [incident.io dashboard](https://app.incident.io/) and click the gear icon (Settings) in the bottom left corner of the screen. Under your current organization section, click **API and Integrations**. Scroll down to the **API and Webhooks** section. Click the **API** tile, then click **Open**. Create (or copy) the API key and store it somewhere safe. incident.io shows the full key only once, at creation time. If you lose it, you will need to create a new key. Pick the key's permissions to match every endpoint your workflows will call. A key that can only do a few things will still connect successfully - the gaps only show up later, when a workflow calls something the key cannot access. ## Connect in Serval In Serval, find **incident.io** in the integrations list and choose to connect it. The form has a single field, **API Key**, shown as a password field with the helper text "Your incident.io API key with appropriate permissions". The label carries no asterisk and the form does no checking of its own, but the key is required - Serval validates it when you submit. Click **Submit**. Serval contacts incident.io to confirm the key works and to identify which incident.io organization it belongs to. If the key is invalid, the save fails with the generic error "Failed to install integration (HTTP 500)" - the underlying reason from incident.io is not shown, so re-check the pasted value and try again. When you later edit the connection, the saved key displays obfuscated - bullet characters with only the last 4 characters visible. Select the pencil icon next to the masked value (or the **Replace** button, if you are reconnecting through the connect dialog) to clear the field, then paste a complete new key and save. On the connection settings form the **Update** button stays disabled until you change something, so an untouched form cannot be resaved by accident. Saving a cleared field without a complete new key fails with an error and leaves the existing credential untouched - every successful save requires a full, valid key. A replacement key must belong to the same incident.io organization. Serval re-identifies the organization from whatever key you save, so a key from a different organization re-points this connection at that organization with no warning. ## Verifying the connection This integration does not ship separate health-check workflows, so the Health Checks panel that appears for some other integrations is absent here. Verification happens at save time instead: every successful save - the first connect or a later key replacement - means Serval reached incident.io with your key, confirmed it is valid, and identified the organization it belongs to. That check confirms validity only, not permissions. Any live key passes it, so a key created with narrow permissions saves cleanly and only reveals its gaps when a workflow calls an endpoint the key cannot access. To exercise the connection beyond save-time validation, run a small workflow that lists incidents (requesting a single result is enough). If the connection saved fine but that call fails, the key is valid but its permissions are too narrow - create a new key with the permissions your workflows need and swap it in. ## Gotchas and troubleshooting Save-time validation only proves the key is valid - any valid key passes it, regardless of permissions. A key created with narrow permissions will save successfully and then fail workflow calls against endpoints it cannot access. Create the key with permissions covering every endpoint your workflows use. Invalid-key errors are generic: a bad or expired key surfaces as this one message with no provider detail, and the underlying reason from incident.io is not shown in the UI. Re-check that you pasted the complete key, then try again. If it still fails, contact support. On edit, the saved key shows only as bullets plus its last 4 characters, and Serval never sends that placeholder back. Every save of this form re-validates whatever key it receives, so saving without entering a full new key fails - the connection settings form shows "Failed to update configuration", and the reconnect dialog shows an error beginning "Failed to update integration". Either way your existing credential is left untouched. To make any change stick, paste the entire new key. Every save re-derives the connected organization from the key itself. Pasting a key from a different incident.io organization re-points the connection at that organization without any warning or guard - double-check which organization a key belongs to before replacing. incident.io returns list data in pages with a continuation cursor. A workflow that needs more than one page must keep requesting, feeding each response's cursor into the next request, until the cursor comes back empty - a single request only ever returns the first page. *** Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your incident.io integration.