If you are hunting for a PagerDuty API key and the instructions you found do not match what you see on screen, you are almost certainly looking at the wrong credential. PagerDuty issues four different things that people casually call an API key, and they are not interchangeable. Paste the wrong one into the wrong endpoint and you get a cryptic authentication error that tells you nothing useful.

This guide covers all four: what each one is, exactly where to click to generate it, how to scope it so a leaked key cannot delete your escalation policies, and how to rotate it without paging anyone at 3am. There is a quick identification trick near the top that resolves most of the confusion in about five seconds.

The four credentials people call a PagerDuty API key

PagerDuty runs two separate APIs, and they take different credentials. The REST API reads and writes configuration data: users, schedules, escalation policies, services, incidents. The Events API does one job, which is accepting events from your monitoring systems to trigger, acknowledge and resolve incidents.

General Access REST API key

An account-level credential that can reach every object in your PagerDuty account. It is not tied to any individual user, which makes it the right choice for server-to-server integrations that must keep working after the engineer who created it leaves the company. Only Admins, Global Admins and the Account Owner can create one.

User Token REST API key

A personal credential scoped to one user's permissions. Requests are restricted to whatever that person is allowed to do, and anything beyond that returns a 403 Forbidden. Useful for scripts you run yourself, and required for certain incident operations. Creating one requires Advanced Permissions on the account.

Events API integration key, also called a routing key

This is the credential most people actually want when they are wiring up a monitoring tool. It lives on an individual service, not on the account, and it only lets you send events in. It cannot read your schedules or modify anything. Any user with a Manager role or above can generate one.

The names "integration key" and "routing key" refer to the same string. PagerDuty's own docs and API reference use both, which is a significant source of the confusion.

Scoped OAuth token from a registered app

The most granular option. You register an app and receive tokens carrying specific scopes, so you can grant read access to schedules without granting write access to users. This is the modern approach for anything you are building for other people to install, and it is worth the extra setup for production integrations.

The five second identification trick

Count the characters. REST API keys, both general access and user token, are 20 character strings. Events API integration keys are 32 characters. If you paste a 20 character key into an Events API call it will fail, and the reverse is also true.

Sending alerts into PagerDuty from a monitoring tool: Events API integration key (32 characters)
Reading schedules, users or on call data: General Access REST API key, read-only (20 characters)
Creating or updating incidents programmatically: User token, or a general access key plus a From header
Building an integration others will install: Scoped OAuth token from a registered app

How to create a General Access REST API key

You need an Admin, Global Admin or Account Owner role. If you do not see the menu described below, that is why.

In the PagerDuty web app, go to Integrations, then Developer Tools, then API Access Keys.
Click Create New API Key.
Enter a description that your future self will understand. "Terraform prod" beats "test key 2" by a wide margin when you are auditing 30 keys two years from now.
Check Read-only API Key unless you have a specific reason not to. This restricts the key to GET calls only.
Click Create Key, then copy the value immediately.

That last point matters more than it looks. The key is displayed in full exactly once. There is no way to retrieve it later. If you lose it, your only option is to delete the key and create a new one, which means updating every system that used it.

Once created, the key appears in the API Access Keys table with its description, creation date, API version, access level and disabled status, including who disabled it and when. That audit trail is genuinely useful during an access review.

How to create a User Token REST API key

Personal keys require Advanced Permissions on your account. The path is different from the account-level one, which trips people up constantly.

Click your User Icon, then My Profile, then User Settings.
Under API Access, click Create API User Token.
Enter a description and click Create Key.
Copy it immediately. Same one time display rule applies.

The resulting key inherits your permissions exactly. This is a feature, not a limitation: if you cannot delete a schedule in the UI, a script running under your token cannot either. The table shows creation date, last used date and API version, and the last used date is the fastest way to find keys nobody needs anymore.

How to find an Events API integration key

Integration keys are not in the developer tools section at all, because they belong to services rather than the account. Open the service you want to send events to, go to its Integrations tab, and either read the existing integration key or add a new integration to generate one.

If you use Event Orchestration to centralise event processing, it uses integration keys the same way. One practical habit: create a separate integration per source system rather than sharing one key across five tools. When you need to cut off a noisy source at 2am, you want to disable one integration, not untangle which of five systems is using the shared key.

Scoping: pick the least powerful key that works

A General Access REST API key with write access can delete every user, schedule and escalation policy in your account. It is a single 20 character string, and it will end up in a CI environment variable, a Terraform state file, and probably a Slack message at some point. Scope accordingly.

Default to read-only

The large majority of real integrations only read. Schedule sync, on-call dashboards, Slack bots that answer "who is on call", headcount reports, all of it is GET traffic. Tick the read-only box. If something breaks later because it needed write access, you will find out quickly and safely, which is a far better failure mode than the alternative.

When you genuinely need a user token

Creating and updating incidents is the main case. PagerDuty wants to attribute those actions to a real person, so it requires either a user-scoped token or a general access key accompanied by a From header containing a valid user's login email. If you are getting a confusing 400 on incident creation with a key that works fine elsewhere, the missing From header is almost always the cause.

One key per integration

Shared keys make rotation impossible in practice, because nobody can enumerate what will break. Create one key per consuming system, name it after that system, and rotation becomes a contained change instead of a risky one.

Authenticating your first request

REST API calls go to api.pagerduty.com and use a Token token= authorization scheme, which is not the more familiar Bearer format. Getting this wrong produces a 401 that looks identical to a bad key.

curl -H "Authorization: Token token=YOUR_20_CHAR_KEY" \
     -H "Accept: application/vnd.pagerduty+json;version=2" \
     "https://api.pagerduty.com/oncalls?limit=10"

Creating an incident additionally needs the From header:

curl -X POST -H "Authorization: Token token=YOUR_20_CHAR_KEY" \
     -H "Accept: application/vnd.pagerduty+json;version=2" \
     -H "From: you@yourcompany.com" \
     -H "Content-Type: application/json" \
     "https://api.pagerduty.com/incidents" -d '{ ... }'

Events API calls are a different endpoint entirely, with the key travelling in the request body as routing_key rather than in a header. Scoped OAuth tokens, unlike REST keys, do use the standard Authorization: Bearer format.

Decoding the errors you will actually hit

401 Unauthorized: bad key, wrong auth scheme (Bearer instead of Token token=), or a disabled key.
403 Forbidden: the key is valid but lacks permission. On a user token this means your own role is insufficient. On a general access key it usually means the key is read-only and you attempted a write.
400 on incident creation: missing or invalid From header.
Events API rejecting your key: you used a 20 character REST key where a 32 character integration key was required.
429 Too Many Requests: rate limited, covered below.

Rotating and revoking keys without breaking production

Most teams never rotate PagerDuty keys, because the tooling that depends on them is exactly the tooling that tells you when things break. That circularity is precisely why it is worth having a routine.

Disable before you delete

PagerDuty draws a useful distinction here. Disabling a general access key stops it working but keeps it in the account, and you can re-enable it at any time. Deleting is permanent and cannot be undone. So when you believe a key is unused, disable it and wait a week. If nothing screams, delete it. If something breaks, re-enable and you have just identified an undocumented dependency for free.

A rotation routine that does not cause an incident

Create the replacement key first, with the same or tighter scope, and a description noting the date.
Deploy the new key to every consumer while the old one is still live. Overlap is what makes this safe.
Verify the new key is working by checking the last used date on the user token table, or by confirming the integration is still functioning.
Disable the old key, do not delete it yet.
Wait a full business cycle, at least a week, so that weekly and monthly jobs get a chance to fail loudly.
Delete the old key and record the rotation.

Do this quarterly for write-capable keys. Read-only keys are lower risk, but the same routine costs very little once it is written down.

When someone leaves

User tokens are the gap in most offboarding checklists. They are personal, they are invisible on the account-level keys page, and they keep working. Account Owners and Admins can delete other users' personal access keys, with the limitation that they cannot delete keys belonging to the Account Owner, an Admin or a Global Admin. Put "check PagerDuty user tokens" in the offboarding runbook.

Rate limits and handling 429s

PagerDuty allows each user 960 requests per minute across all of that user's API keys. Registered apps get 960 requests per minute against each account they are authorised to access. Note the shape of that limit carefully: it is per user, not per key, so creating a second key for the same user buys you nothing in additional throughput. If you need more headroom, that is an argument for a registered app rather than another token.

When you exceed the limit you get an HTTP 429 with a Retry-After header telling you how many seconds to wait. Responses also carry rate limit headers (ratelimit-limit, ratelimit-remaining and ratelimit-reset) so you can back off before you hit the wall rather than after.

Two practical habits. First, respect Retry-After rather than implementing a fixed sleep, because your fixed number will be wrong. Second, cache aggressively. On-call schedules change infrequently, so polling the oncalls endpoint every thirty seconds is almost always wasted quota. Once a minute, cached, is plenty for nearly every dashboard.

Where API keys fit in a Slack-first on-call setup

The most common reason engineering teams generate a PagerDuty API key is not to build something exotic. It is to get on-call information out of PagerDuty and into the place where the team actually works, which for most teams is Slack. Knowing who is on call should not require opening a separate tab, and an escalation should not depend on someone remembering a rotation by heart.

Worth knowing before you over-scope: a read-only general access key is sufficient for the entire read side of this. Syncing schedules into Slack user groups, keeping a channel topic current with the on-call name, resolving @oncall mentions to a real human, and routing tickets to whoever is currently on rotation are all GET operations. You do not need a write-capable key for any of it.

This is also why the coexistence pattern works well. Plenty of teams keep PagerDuty for phone and SMS paging, where it is strong, while running day to day rotations, handoffs, overrides and ticket assignment in Slack, where the team already is. A read-only key is the bridge, and it carries close to zero blast radius if it leaks.

If you are setting that up with Pagerly, the step by step version lives in our guide to retrieving a PagerDuty API key, which walks through generating the key and connecting it.

Key takeaways

Four different credentials get called a PagerDuty API key. Count the characters: 20 means REST, 32 means Events API integration key.
General access keys are account wide and survive staff changes. User tokens inherit one person's permissions and are frequently missed at offboarding.
Integration keys and routing keys are the same thing, which explains a lot of the documentation confusion.
Tick read-only unless you have a specific reason not to. Most integrations only read.
Copy the key at creation. It is shown in full exactly once, and there is no recovery path.
Incident creation needs a user token or a From header with a valid user email.
Rotate with overlap: create, deploy, verify, disable, wait a week, delete.
Rate limits are 960 requests per minute per user across all their keys. Respect Retry-After and cache schedule data.

None of this is difficult, but nearly all of it is undocumented in the place you look first, which is why teams lose an afternoon to a 401 that turns out to be a Bearer prefix. Generate the narrowest key that does the job, name it after the system consuming it, and write down where it went. Future you, mid incident, will be grateful.