Part of the Phoenix Alerts Management API reference.

API keys are how your tools authenticate to Phoenix Alerts. There are two types:

Ingestion keys (pi_ prefix) send alerts in, and can also acknowledge or resolve an alert through PATCH /v1/alerts/{alert_uuid} — useful if your monitoring tool clears its own alerts. They can't touch services, teams, users, or other account settings. Use one per monitoring tool so you can revoke a single integration without affecting the others.
Management keys (pm_ prefix) have full authority over your account's configuration: manage services, teams, users, schedules, and escalation policies, and create or revoke other keys. They cannot send alerts in, and they can't create a new Phoenix Alerts account. Use these for admin scripts or tools that configure your account.

A management key's authority cannot be narrowed. If you only need to send alerts, use an ingestion key instead. To take authority away from a management key, revoke it — there's no separate scoping step.

Your account can have at most 25 active keys at once. Revoke one before creating another if you're at the limit.

Create a key

This creates an additional key, so it needs an existing management key to call. Your first management key comes from the Phoenix Alerts app inside Jira — the account owner creates it there, on the API keys screen.

POST /v1/tenants/me/api-keys

Request body:

Field	Type	Required	Notes
`name`	string	yes	1–200 characters.
`key_type`	string	no	`"INGESTION"` or `"MANAGEMENT"`. Defaults to `"INGESTION"` when omitted.

Example request body:

{"name": "Datadog integration"}

Response (201):

{
  "object": "api_key",
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "key_type": "INGESTION",
  "key_prefix": "pi_a3f7b",
  "name": "Datadog integration",
  "created_at": "2026-06-12T00:00:00.000Z",
  "raw_key": "pi_a3f7b_EXAMPLE_KEY_NOT_REAL"
}

raw_key is shown exactly once, in this response. Phoenix Alerts stores only a hash of it — there is no way to retrieve it again. Copy it into your monitoring tool or secrets manager immediately.

To create a management key instead, send "key_type": "MANAGEMENT":

Example request body:

{"name": "Jira App Key", "key_type": "MANAGEMENT"}

List your keys

GET /v1/tenants/me/api-keys

Response (200):

{
  "object": "list",
  "data": [
    {
      "object": "api_key",
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "key_type": "MANAGEMENT",
      "key_prefix": "pm_a3f7b",
      "name": "Jira App Key",
      "created_at": "2026-06-12T00:00:00.000Z",
      "last_used_at": "2026-06-12T08:00:00.000Z"
    }
  ]
}

The raw key value is never included here — only the prefix, so you can tell your keys apart. last_used_at is null for a key that has never been used.

Rotate a key

Rotation atomically creates a new key with the same type and revokes the old one, without changing your active-key count against the 25-key limit.

POST /v1/tenants/me/api-keys/{key_id}/rotate

Request body (optional):

Field	Type	Required	Notes
`name`	string	no	New display name. Omit to keep the existing name.

Response (201):

{
  "object": "api_key",
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "key_type": "MANAGEMENT",
  "key_prefix": "pm_z9k2m",
  "name": "Jira App Key",
  "created_at": "2026-06-12T01:00:00.000Z",
  "raw_key": "pm_z9k2m_EXAMPLE_KEY_NOT_REAL",
  "rotated_from_key": "d4e5f6a7-b8c9-0123-defa-234567890123"
}

Update your integration with the new raw_key right away — the old key stops working immediately.

Revoke a key

DELETE /v1/tenants/me/api-keys/{key_id}

Returns 204 with no body. Revocation is immediate and cannot be undone — the key is rejected on every request from then on.