# Connect PagerDuty > Know at a glance whether you have to move. Incidents assigned to you, your teams' incidents and your on-call shifts reach your Mac's notch, read with your own PagerDuty token. Source: https://coisland.app/docs/connect-pagerduty/ ## What you need - **You need:** API User Token, from Your avatar › My Profile › User Settings - **The form asks:** Connector name, User API token - **You can watch:** Assigned to me, Incidents, Status changes, Acknowledged too long, On call now, Shift starting soon - **Access:** GET requests only; it never acknowledges or resolves To connect PagerDuty to CoIsland you need one thing: an API User Token from your own PagerDuty profile. No admin, no app to register, no OAuth. CoIsland calls PagerDuty's REST API straight from your Mac, with no CoIsland server or account in between, keeps the token in your login Keychain, and only ever reads. This page covers the token, the connector form, the six PagerDuty monitor kinds with queries you can paste, and the errors you may meet. ## Create a PagerDuty API User Token 1. Sign in to PagerDuty at `https://your-subdomain.pagerduty.com`, or `https://your-subdomain.eu.pagerduty.com` for an account in the EU region. 2. Select your user icon at the top right, then **My Profile**, then the **User Settings** tab. 3. Under **API Access**, select **Create API User Token**. 4. Enter a description, such as `CoIsland`, then select **Create Key**. 5. Copy the key now: PagerDuty shows it in full only this once. If you lose it, delete it and create another. The token acts as you, with your permissions: CoIsland sees the incidents, services, teams and schedules you can see in PagerDuty, and nothing more. On accounts with Advanced Permissions, the Restricted Access, Observer, Responder and Manager roles can create one; Stakeholders cannot. Do not use an account-wide (general access) key: CoIsland needs to know who "me" is, and those keys belong to no user. ## Connect PagerDuty in CoIsland Open **Settings › Connectors**, click **+** at the top right (or **Add Connector** when you have none yet), and choose **PagerDuty**. | Field | What to enter | |---|---| | Connector name | What monitors call it: `pagerduty`, or your subdomain once tested. Letters, digits, `_` and `-`. | | User API token | The token you created. | Then click **Test connector**, which saves nothing. It calls `GET /users/me` on `api.pagerduty.com` and, if the US region refuses the token, once more on `api.eu.pagerduty.com`. A success reads **Connected**, with your name, email, account address, region and role. There is no region field to get wrong: your account's address says whether it is in the US or the EU region. Click **Add Connector**. The name, the region and the account address go to `~/Library/Application Support/CoIsland/connectors.json`, the token to your login Keychain. The token is only ever sent to `https://api.pagerduty.com` or `https://api.eu.pagerduty.com`, in the `Authorization` header, whatever that file says. The first PagerDuty connector becomes the default. ## Choose what to watch: the six PagerDuty monitor kinds Open **Monitors**, add a monitor and choose **PagerDuty**. Each kind is a few `key:value` words, written for you by the editor's fields: services, teams, escalation policies and schedules are picked by name and saved as IDs. The examples check every minute; a new monitor checks every 15 minutes unless you choose otherwise, from 30 seconds up. A new-items monitor's first check records what is already there and raises nothing. ### Assigned to me An open incident alerts when it is assigned to you, and again when it comes back to you by escalation or reassignment: each assignment has its own time. ```text status:triggered,acknowledged urgency:high ``` ### Incidents A matching incident alerts once, when it first appears. Pick services, teams (`team:mine` is your teams, read at each check) or `scope:all` for every incident you can see. Resolved incidents, when asked for, are those of the last 24 hours. ```text team:mine status:triggered ``` With the rule **Count crosses a threshold** set to more than 10, the same query is an incident storm alert. ### Status changes The same incident alerts each time it is in a status it was not in at the last check: triggered, acknowledged, resolved. Incidents of the last 24 hours. ```text team:mine ``` ### Acknowledged too long An acknowledged incident alerts once when it has sat acknowledged for longer than `older:`, from 5 minutes to 24 hours. A new acknowledgement starts the clock again. ```text older:30m team:mine ``` ### On call now Your current on-call shifts are the rows: a shift that starts alerts, and the notch card reads "On call until Fri 09:00". With **Count crosses a threshold** set to equals 0, CoIsland tells you when you go off call instead. Narrow it with `policy:` or `schedule:`. ```text user:me ``` ### Shift starting soon One of your shifts alerts once when it starts within `within:`, from 5 minutes to 7 days, which must be longer than the check interval. ```text within:1h ``` Click **Test** to run the query once: nothing is saved or alerted. A check reads up to 1,000 incidents; when more match, nothing new is compared and the monitor asks you to narrow it, while a count rule still fires. ## What a PagerDuty alert shows The notch lists each incident as `Checkout API #1234 · Triggered · High · you`: where, how bad, who has it. Clicking it opens the alert in CoIsland. The incident's card fills in live: assignees, urgency, priority, service, escalation policy, teams, alert counts, the conference bridge, the first alert's details as a table, and a **Timeline** of notes and log entries with the one the alert is about first. **Open in PagerDuty** goes to the incident. A shift's card says who is on call beside you, who is next, or who hands over to you. ## What a PagerDuty monitor's watch file looks like ```sql -- name: Triggered on my teams -- kind: pagerduty.incidents -- connector: pagerduty -- every: 1m -- alert: new-rows -- sound: Glass team:mine status:triggered ``` The kinds are `pagerduty.assigned`, `pagerduty.incidents`, `pagerduty.status`, `pagerduty.stale-acks`, `pagerduty.oncall-now` and `pagerduty.oncall-next`. Changing the query, the kind or the connector starts a new baseline. [Watch files](https://coisland.app/docs/watch-files/) lists every header key. ## Rate limits PagerDuty allows 960 REST requests a minute per user, shared by all of that user's keys. A check costs one request per 100 incidents, plus a read of who you are every ten minutes; six monitors checking every minute use about 1% of it. If you also run other PagerDuty tools as yourself, they share the same limit. When PagerDuty asks CoIsland to slow down, checks back off on their own. ## Troubleshooting PagerDuty connector errors - **The token was refused. Check it has not expired or been revoked. Create a new API User Token under My Profile › User Settings.** PagerDuty answered 401: the token was mistyped, you deleted it, your user was removed, or an account Owner or Admin deleted it (they can delete other users' personal keys). Create a new token, add it as a new connector, and pick that connector under **Runs on** in each monitor. - **Not allowed. The token may lack a permission.** PagerDuty answered 403: your role was lowered, or you can no longer see a service or team the monitor names. - **Your PagerDuty plan does not include team or urgency filters. Remove them.** PagerDuty answered 402: your plan lacks the `teams` or `urgencies` ability. The editor hides those fields when your plan lacks them. - **PagerDuty refused the request:** then PagerDuty's reasons, for a request it found invalid. - **Rate limited; retry after 51s.** PagerDuty answered 429. The next check tries again. - **Pick a service or a team, or choose all incidents.** An Incidents, Status changes or Acknowledged too long monitor needs `service:`, `team:` or `scope:all`. - **team:mine: you are on no PagerDuty team.** Pick services or teams by name instead. - **This incident no longer exists in PagerDuty (merged or deleted). The saved copy is shown.** The alert keeps the incident as it was. - **No PagerDuty connector is named acme.** A monitor's `-- connector:` line names a connector that does not exist. ## Common questions ### Does CoIsland need PagerDuty admin rights? No. Any user who can create an API User Token under their own profile can connect: Responders, Managers, Observers and Restricted Access users on Advanced Permissions accounts. ### Can CoIsland acknowledge or resolve incidents? No. It only reads. Acknowledge and resolve in PagerDuty, from the incident **Open in PagerDuty** opens. ### Does it work with a PagerDuty account in the EU region? Yes. CoIsland reads the region from your account when you test the connector, and calls `api.eu.pagerduty.com` from then on. Next: [Getting started](https://coisland.app/docs/getting-started/) for the rest of the app, or the [PagerDuty connector](https://coisland.app/pagerduty/) for everything it can watch.