If your PagerDuty integration is returning an authentication error that makes no sense, there is a good chance you are holding the right credential for the wrong API. A PagerDuty integration key and a PagerDuty API key are completely different things, they are generated in completely different places, and they are not interchangeable in either direction.

Here is the fastest way to tell them apart, before we get into why the naming is such a mess: count the characters. Twenty characters means a REST API key. Thirty two characters means an Events API integration key. That single check resolves the majority of these errors.

Why PagerDuty integration key naming confuses everyone

The confusion is not your fault. It comes from three real sources, and understanding them makes the rest of this obvious.

One product, two separate APIs

PagerDuty runs two APIs that have almost nothing to do with each other. The REST API manages configuration: users, teams, schedules, escalation policies, services, and incident records. The Events API does exactly one job, which is receiving events from monitoring systems so PagerDuty can trigger, acknowledge or resolve incidents.

Different jobs, different credentials, different endpoints, different auth mechanisms. Most tools have one API and one key. PagerDuty has two of each, and the documentation for one rarely reminds you that the other exists.

Integration key and routing key are the same thing

This one causes real damage. PagerDuty's product UI calls it an integration key. The Events API v2 request body calls the same value routing_key. Third party tools split the difference unpredictably: some ask for a "PagerDuty routing key", some for an "integration key", some for a "service key", and some just say "PagerDuty key" and leave you guessing.

They all mean the same 32 character string from a service's Integrations tab. If a tool asks for a routing key and PagerDuty never showed you anything called that, you are looking for the integration key.

Keys live in two different parts of the UI

REST API keys are account level, under Integrations then Developer Tools then API Access Keys. Integration keys are service level, on each individual service's Integrations tab. People who go hunting in Developer Tools for an integration key will never find one, because it is not there and never was.

The four credentials, side by side

General Access REST API key

Twenty characters. Account wide, not tied to any person, so it survives staff turnover. Created by Admins, Global Admins or the Account Owner under Integrations, Developer Tools, API Access Keys. Can be restricted to read-only at creation, which limits it to GET calls. This is the right credential for a server side integration that reads schedules or on-call data.

User Token REST API key

Twenty characters. Scoped to one person's permissions, so anything that person cannot do returns 403 Forbidden. Created under your User Icon, My Profile, User Settings, then API Access. Requires Advanced Permissions on the account. Right for personal scripts, and required (or a From header) for creating incidents.

Events API integration key, also called a routing key

Thirty two characters. Belongs to a single service, found on that service's Integrations tab. Any user with a Manager role or above can generate one. It can only send events in. It cannot read your schedules, cannot list your users, and cannot delete anything, which makes it by far the lowest risk credential of the four. This is what your monitoring tools want.

Scoped OAuth token

Issued to a registered app with specific scopes, so you can grant read access to schedules without granting write access to users. Uses the standard Authorization: Bearer format, unlike REST keys. The right answer for anything you are distributing for other people to install, and for production integrations where least privilege matters.

Which key does my tool actually want?

Work backwards from the direction of the data. This single question resolves nearly every case.

Data flowing into PagerDuty (an alert, an event, a trigger from a monitoring system): integration key, 32 characters.
Data flowing out of PagerDuty (reading who is on call, listing schedules, exporting incidents): REST API key, 20 characters.
Both directions, or acting as a user (creating incidents, adding notes, reassigning): REST API key with a From header, or a user token.

Some concrete mappings. A monitoring tool like Prometheus Alertmanager, Nagios, Zabbix or a cloud provider alarm needs an integration key. A Slack bot answering "who is on call right now" needs a read-only REST key. A Terraform provider managing your PagerDuty configuration needs a write-capable REST key. A status page pulling open incidents needs a read-only REST key. A CI pipeline that opens an incident on a failed deploy needs a REST key plus a From header, or an integration key if you would rather send it as an event, which is usually the better choice.

That last example is worth sitting with. Many teams reach for the REST API to create incidents when sending an event to the Events API would be simpler, safer and more idiomatic. Events get deduplicated, grouped and processed by Event Orchestration. REST-created incidents skip all of that. If the thing you are reporting is an alert, send it as an event.

How to find each key

Finding an integration key

Go to Services and open the service that should receive these events.
Open its Integrations tab.
Either copy the integration key from an existing integration, or add a new integration and pick the vendor from the list.

Create one integration per source system rather than reusing a single key everywhere. When a source goes haywire at 2am, you want to disable one integration, not work out which of six tools is using the shared key.

Finding a REST API key

Integrations, then Developer Tools, then API Access Keys, then Create New API Key. Tick Read-only API Key unless you have a specific reason not to. Copy it immediately, because the value is displayed in full exactly once and there is no way to retrieve it afterwards. Lose it and your only option is deleting the key and creating a new one.

Error messages, decoded

Each of these has a specific cause, and none of the messages tell you what it is.

401 Unauthorized on a REST call: either a bad key, or you used Authorization: Bearer when PagerDuty's REST API wants Authorization: Token token=YOUR_KEY. The Bearer mistake is extremely common because nearly every other API uses it.
403 Forbidden on a REST call: the key is valid but not allowed. On a read-only key this means you attempted a write. On a user token it means your own role is insufficient.
400 when creating an incident: missing or invalid From header. It must contain the login email of a real user on the account.
Events API rejecting your key: you supplied a 20 character REST key where a 32 character integration key belongs. Count the characters.
Events accepted but no incident appears: the key is valid but points at a different service than you expect, or the service has a suppressing Event Orchestration rule. Check which service the key belongs to before assuming the key is broken.
429 Too Many Requests: rate limited. REST allows 960 requests per minute per user across all of that user's keys, so adding a second key for the same user gains you nothing.

The fifth thing people mistake for a key: webhook secrets

Once you start wiring PagerDuty into other systems you will meet a credential that is not an API key at all, and confusing it with one wastes a surprising amount of time.

Webhook subscriptions send data from PagerDuty out to your endpoint when something happens, such as an incident being triggered or resolved. They come with a signing secret, which exists so your receiving endpoint can verify that an incoming payload genuinely came from PagerDuty and was not forged by somebody who guessed your URL.

A signing secret is not an authentication credential. You never send it anywhere. You use it locally to compute a signature over the received request body and compare that against the signature header PagerDuty included. If they match, the payload is authentic.

The distinction that matters: API keys and integration keys are things you present to PagerDuty to prove who you are. A webhook signing secret is something PagerDuty uses to prove to you who it is. Opposite directions entirely. If you find yourself trying to paste a signing secret into an Authorization header, stop, because you are solving the wrong problem.

Verify a key before you ship it

Every one of these key types can be tested in about ten seconds, which is considerably faster than deploying and reading logs. Do this before you put a key into CI.

Testing a REST API key

Call an endpoint that reads something harmless. If you get JSON back, the key and the auth scheme are both correct.

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Token token=YOUR_20_CHAR_KEY" \
  -H "Accept: application/vnd.pagerduty+json;version=2" \
  "https://api.pagerduty.com/users?limit=1"

A 200 means you are good. A 401 means the key or the scheme is wrong. A 403 means the key is valid but lacks permission, which on a read-only key doing a read should not happen, so check you are hitting the endpoint you think you are.

Testing whether a key is read-only

If you inherited a key and do not know its access level, attempt a harmless write and see if it is refused. A 403 confirms read-only, which is the answer you want. Anything else means you are holding a write-capable account key and should treat it accordingly.

Testing an integration key

Send a real event to the Events API, then resolve it. It will create a genuine incident on that service, so do this on a test service or warn whoever is on call first. If the response contains a status of success and a dedup key, the integration key is valid and pointed at a real service.

If you get success but no incident shows up where you expected, the key belongs to a different service than you assumed. That is a configuration problem, not a credential problem, and no amount of regenerating the key will fix it.

Security: these keys are not equally dangerous

Treating all four as equivalent secrets is a mistake in both directions. It makes people paranoid about harmless integration keys and careless about genuinely dangerous REST keys.

Ranked by blast radius

Write-capable General Access REST key: highest risk. Can delete every user, schedule, service and escalation policy in the account. Guard it like a production database credential.
User token: risk equal to that person's permissions, which for an admin is effectively the same as above.
Read-only General Access REST key: exposes your org chart, schedules and contact data. A real privacy concern, but it cannot destroy anything.
Integration key: lowest risk. A leaked one lets someone create noise on one service. Annoying, easily fixed by rotating that single integration, and it cannot read or delete anything.

The practical consequence: do not let integration key caution slow down your monitoring setup, and do not let REST key convenience talk you into a write-capable account key when read-only would do. The default should be the narrowest credential that completes the job.

Rotation differs by type

Integration keys rotate cleanly. Add a new integration to the service, move the source system over, delete the old integration. No account wide coordination required.

REST keys need more care because you often cannot enumerate every consumer. PagerDuty lets you disable a general access key without deleting it, and disabled keys can be re-enabled at any time. So disable, wait a week, and see what screams. Anything that breaks has just documented itself. Delete only once the waiting period passes, because deletion is permanent.

Getting on-call data into Slack without over-scoping

The most common reason to create a REST key at all is not building something elaborate. It is getting on-call information out of PagerDuty and into Slack, where the team already works. Knowing who is on call should not require opening another tab, and routing a ticket should not depend on someone remembering the rotation.

Worth being precise here, because this is where over-scoping usually happens: every part of that is a read operation. Syncing schedules into Slack user groups, keeping a channel topic current with the on-call name, resolving @oncall to a real person, routing tickets to whoever is on rotation. All GET calls. A read-only key covers the lot, and if it leaks, nobody can delete your escalation policies with it.

This is also why keeping PagerDuty for phone and SMS paging while running daily rotations and handoffs in Slack works so well as a pattern. The integration key keeps your alerts flowing in, a read-only REST key bridges the schedule data out, and neither credential can do much damage. If you are wiring that up with Pagerly, our guide to retrieving a PagerDuty API key covers the exact steps.

Key takeaways

Count the characters first. Twenty is a REST API key, thirty two is an Events API integration key.
Integration key and routing key are two names for the same value. PagerDuty's UI says one, the Events API payload says the other.
Data going into PagerDuty needs an integration key. Data coming out needs a REST key.
REST keys are account level under Developer Tools. Integration keys are service level on a service's Integrations tab. They are not in the same place and never have been.
PagerDuty's REST API uses Authorization: Token token=, not Bearer. Scoped OAuth tokens do use Bearer.
Use the Events API rather than REST incident creation for anything alert shaped, so you get deduplication and orchestration.
Blast radius varies enormously. A write-capable REST key can destroy your account. An integration key can create noise on one service.
Disable REST keys before deleting them, and wait a week to discover undocumented dependencies safely.

Almost every hour lost to PagerDuty authentication comes down to one of these mismatches, and almost none of them produce an error message that points at the real cause. Count the characters, check the direction the data flows, and confirm you are in the right corner of the UI. That covers it.