API keys
Create the narrowest credential that your sender or automation needs.
Choose an access level
| Access | Use | Permissions |
|---|---|---|
| Alert ingest | Monitoring, CI, and simple senders. | Send, acknowledge, and resolve alerts. |
| Full product API | Trusted agents and organization automation. | Read and change everything that the creating admin can administer. |
Use alert-ingest access unless the client must manage product configuration.
Create an API key
- Open Integrations → API keys.
- Find API keys.
- Enter a name that identifies the client.
- Enable full product access only when the client requires it.
- Select Create key.
- Copy the key from the one-time prompt.
Acked does not show the secret again. Store it directly in the sender or a secret manager.
Authenticate a request
Send the key as a bearer token.
Authorization: Bearer ak_YOUR_KEYFull product API requests use the customer /api/* routes. Send the active organization when the route is organization-scoped.
X-Acked-Org: org_01hexampleProtect credentials
- Create one key for each client or environment.
- Use names that identify the owner and purpose.
- Keep keys out of source, logs, screenshots, and chat.
- Use the narrowest access level.
- Revoke a key when a client is retired or the secret is exposed.
Rotate a key
API keys do not have an in-place rotation action. Create a replacement, update the client, verify a request, and revoke the previous key.
- Create a new key with the same required access.
- Update the client secret.
- Send a test request.
- Revoke the previous key.
Revoke a key
Find the key under Integrations → API keys. Select Revoke and confirm.
Requests using the revoked key start failing within one minute.
Do not confuse keys with source credentials
A source ingest URL or PagerDuty routing key authenticates one source for one service. An API key can select services and call explicit API routes.
Manage source credentials on the service page. Manage API keys under Integrations.