API Keys and Scopes

API keys are how the Developer API knows who is calling and what the caller may do. This article covers creating a key and choosing when it expires, the reminders Pingara emails before it does, rotating it, what the keys list shows, storing a key safely, the scopes a key can carry, how write authority is checked, and what a 401 or 403 means. The endpoints themselves are in the Developer API reference.

Create an API key

1. Sign in to Pingara and switch to the organization you want to script against.
2. Open Settings → API & webhooks (the mobile navigation still labels this tab API).
3. Click Create key. In the Create an API key dialog, enter a recognizable name for the key (for example CI deploy or Grafana sync), tick what it may do under Scopes, choose when it expires under Expires, and click Create key. See Choosing scopes and Key expiry.
4. Copy the full key immediately. It is shown exactly once and starts with the prefix pgr_. Pingara only stores a SHA-256 hash, so a lost key cannot be recovered. Revoke it and create a new one.

Only owners and admins can create, rotate or revoke keys. Reading through the API is available on every plan, and so is audit log access. A scope that can change something needs the Pro plan. The number of active keys an organization can hold at once is also plan-gated: 2 on Free, 25 on Pro. An expired or revoked key does not count toward it. A key you have rotated still counts until it stops working, see Rotating a key.

Choosing scopes

The dialog lists every scope a key can be given today, grouped under Monitors, Alert policies, Status pages, Webhook subscriptions and Across the API. Each tick says what it lets the key do, and Key scopes lists which scope each tick gives. Nothing is ticked when the dialog opens, and it does not create a key until you tick at least one scope.

• A scope that includes another ticks it too. For example, ticking Create and change monitors also ticks View monitors and Resume monitors, and each says "Included with Create and change monitors." To remove one, untick the scope that includes it.
• Some ticks are never chosen for you. Read everything, Audit log access and Delete monitors give a key personal data or the power to destroy something, so only tick them when a key needs them. Read everything is the read scope: it reads every endpoint except the audit log, including incidents, which show the name and email address of whoever acknowledged or resolved each one.
• On the Free plan, the ticks for scopes that change something can't be ticked, and the dialog shows "Scopes that change something need Pro." The read ticks work on every plan.
• The legacy write scope is not offered, because it can no longer be given to a new key. Keys that already have read and write access keep it, including when you rotate them, see Key scopes.

To let a key read the audit log, tick Audit log access. It is off by default, it is available on every plan, and a key that has it shows an Audit log badge beside its scope in the keys list. You cannot create a key with only that scope: ticking it also ticks Read everything, which the audit log needs.

Key expiry

You choose when a key expires when you create it. Under Expires in the create dialog, choose 30 days, 90 days, 365 days or Never. 90 days is selected by default, for a read-only key too: Never has to be chosen on purpose.

A key with a scope that can change something, or with Audit log access, must expire. Only a key whose scopes all only read, and none of which is audit:read, may be set to Never. While such a scope is ticked, Never is unavailable and the dialog says "Keys with audit log access, or with any access that changes something, must expire." If Never is already selected when you tick one, the dialog does not create the key and says "Keys with audit log access, or with any access that changes something, must expire. Choose 30, 90 or 365 days." Pingara enforces the same rule on the server, not only in the dialog.

The keys list shows each key's expiry in its Expires column: a date, Never expires, or a dash for a revoked key. The dialog that shows a new key once also shows its exact expiry time. When a key reaches its expiry date it gets 401, exactly like a revoked key, its Status changes to Expired, and it stops counting toward your plan's key limit. Keys created before expiry existed have no expiry date, show Never expires and keep working until you revoke them.

Expiry reminders

Pingara emails a reminder before a key expires, so an integration does not stop without warning.

• When: 14 days before the key expires, 3 days before, and once when it has expired. Each reminder is sent at most once. A key first due a reminder less than 3 days before it expires gets only the 3-day reminder, and a key that expired more than 7 days ago gets no notice. A reminder can arrive up to an hour after it falls due.
• Who: every current owner and admin of the organization, and the member who created the key if they are still in the organization, whatever their role now. Each person gets their own email.
• What it says: the key's name, when it expires, when it was last used, its scopes, and a link to Settings → API & webhooks. It never contains the key, any part of it, or who created it.
• Which keys get none: a key with no expiry date, and a key that already gets 401 for another reason: revoked, suspended, or created by someone who is no longer a member. A key you have rotated gets none either. Its replacement keeps the same expiry date and the reminders already sent for it, so a rotation does not repeat a reminder.

Rotating a key does not move its expiry date. To keep an integration working past that date, create a new key, switch the integration to it, then revoke the old one. An integration can also read its own key's expiry from GET /api/v1/me, as apiKey.expiresAt.

Rotating a key

Rotating replaces a key without an outage. Owners and admins rotate a key with the Rotate button on its row in the keys list:

1. Click Rotate. The dialog shows when the current key will stop working and what expiry the new key gets.
2. Click Rotate key. Pingara creates a new key with the same name, scope and expiry date, and shows it once, with the same warning as when you create a key. Copy it.
3. Update your integration to use the new key before the current key stops.

What to expect:

• The current key keeps working for 24 hours, or until its own expiry date if that is sooner. Its Status reads Replaced, with the time it stops working, and then Expired. A replaced key has no Rotate button: rotate its replacement instead.

• Rotating never extends a key's life. The new key has the expiry date the old one had, not a fresh 30, 90 or 365 days, and the dialog states it: "The new key keeps the current key's expiry" with the time, or "The new key never expires, like the current one." for a read-only key with no expiry. The one exception is a write or audit log key from before expiry existed, which has no expiry date: its replacement expires in 90 days, and the dialog says so.

• If the current key expires within 24 hours, the new key expires at the same moment. Both keys stop together, so the rotation does not buy you time. The dialog says "The new key expires at the same time, because rotating never extends a key's life. If your integrations need a key after then, create a new key instead.", and the dialog that shows the new key repeats it. Create a new key if an integration needs one beyond that time.

• You become the new key's creator. A key acts with the access of the member who created it, so the replacement belongs to whoever rotated it, not to the member who created the original. That also means the new key is revoked if you later leave or are removed from the organization. The Created column of the keys list shows who created each key.

• Rotating does not need a free slot, but both keys count toward your plan's key limit until the current one stops. You can rotate when you are at or over the limit. What it costs you depends on where you start:

  • If the rotation brings the organization exactly to its limit, you cannot create another key for up to 24 hours, until the current key stops.
  • If the organization is already at its limit, or over it, the dialog says "Your organization is already at its limit, so you won't be able to create another key until fewer keys are active than your plan allows." When the organization is at or over the limit, the keys card replaces the Create key button. On Free it shows the banner "API key limit reached. Upgrade to Pro for more active keys." On Pro, when more keys are active than the plan allows, it says how many are active and that you can create another once fewer than the limit are. On either plan, if a replaced key is still counting, it adds when the next one stops working.

  An organization can also have only as many replaced keys waiting out their 24 hours as its plan allows active keys. Past that, wait for one to stop, or revoke it, and try again.

• A suspended, expired or revoked key cannot be rotated. Create a new key instead.

• The rotation appears in the audit log as API key rotated.

What the Status column shows

Storing keys safely

• Treat the key like a password. Anyone with it can do everything its scopes allow in your organization. Give each key only the scopes it needs.
• Give a key Audit log access only if it needs to read the audit log, which holds your members' IP addresses.
• Store keys in your secrets manager (1Password, Vault, AWS Secrets Manager, GitHub Actions secrets, etc.), never in source control.
• Every key is pgr_ followed by 64 lowercase hexadecimal characters. That fixed shape lets a secret scanner recognize one, so add it as a rule in the scanner you run on your own repositories (gitleaks, for example, takes custom rules) to catch a key committed by mistake. If one ever is, revoke it and create a new one: removing the commit does not undo the exposure.
• Use a dedicated key per integration so you can revoke one without breaking the rest.
• Some keys are revoked for you. When a member is removed from an organization or leaves it, every key they created in that organization is revoked at that moment, and keys they created in other organizations are not affected. Before you remove someone, rotate or replace any key they created that an integration still needs, and update the integration first, because their key stops working the moment they go. If Pingara support deactivates a user account, every key that user created is revoked. If a member undoes a sign-in email change (see Managing Your Profile), every key that account created at or after the moment the change was requested is revoked, in any organization. A revoked key gets 401, and each one shows in the audit log as API key revoked with System as the actor. Create a new key if an integration stops working after one of these.
• A key can stop working without being revoked. If its creator is no longer a member of the organization, for example because they left before keys were revoked automatically, requests with the key are refused (a read gets 401 and a write gets 403) and its Status reads Not working. Rotate it to get a working key, or revoke it.

Authentication

Every request must include an Authorization header:

curl https://api.pingara.io/api/v1/me \
  -H "Authorization: Bearer pgr_abcdef0123456789..."

Successful responses return JSON with HTTP 200. Authentication failures return 401:

{ "error": "Unauthorized", "code": "unauthorized", "retryable": false, "requestId": "6f0c2a4e-1b7d-4c55-9e2f-3a8d0b1c7e94" }

This message is deliberately identical for every failure mode, whether that's a missing header, the wrong scheme, a malformed key, a key that doesn't match any hash in your organization, a key that has been revoked or has expired, or, on a read, a key whose creator is no longer a member of the organization. Pingara never returns a more specific reason, so a caller can't probe which case they hit to learn whether a given key exists. Don't branch your error handling on the message text; treat any 401 as "not authenticated" and re-check the header.

Key scopes

Every key carries a list of scopes, returned by GET /api/v1/me. An endpoint accepts any one of the scope sets listed for it in the x-pingara-scopes field of the OpenAPI contract; the tables below group the same scopes by what they let a key do.

Coarse scopes apply across the API:

Resource scopes apply to one kind of resource. A scope that includes another lists it in the third column, and a key stores both:

In the create dialog, each scope is a tick with this label:

Creating a monitor with a non-empty alertPolicyIds needs monitors:write and alerts:write (or the legacy write). Incidents, incident acknowledgement and updates, GET /api/v1/me and the webhook subscription writes have no resource scope yet. Reading them needs read (webhook subscriptions also accept webhooks:read), and changing them needs the legacy write, so a key created today cannot call the write ones.

Keys created before scopes were enforced carry ["read"] and are unaffected for reading, except for the audit log, which they cannot read. A scope cannot be added to an existing key; create a new key.

The plan is checked on every change. A request that creates or changes something is checked against your organization's current plan as well as the key's scopes. If the only scope that would allow it is one your plan does not include, for example a key holding write in an organization that is now on Free, the API returns 403 with:

{ "error": "This API key's \"write\" scope is not available on your organization's current plan." }

Reads are never refused for the plan: every scope a read accepts is available on every plan.

If a key lacks the scope an endpoint requires, the API returns 403, not 401:

{
  "error": "This API key does not have the required \"write\" scope.",
  "code": "insufficient_scope",
  "retryable": false,
  "requestId": "6f0c2a4e-1b7d-4c55-9e2f-3a8d0b1c7e94",
  "details": { "requiredScope": "write" }
}

The distinction is deliberate and safe to rely on. A 401 means Pingara could not authenticate you at all, and its message is uninformative by design. A 403 means the key is valid and you are holding it, so naming the missing scope tells you nothing you didn't already know, and it is the only way to diagnose a misconfigured integration. Branch on the status code, not on the message: a 401 may be worth retrying with a different key, but a 403 never succeeds on retry. Fix the key's scopes instead.

Write authority is re-checked on every request

A key's ability to write is checked against its creator's current organization membership and role on every single write call, not cached from when the key was created. Two things protect you when a creator goes:

• Their keys are revoked. Removing a member, or a member leaving, revokes every key they created in that organization at that moment. See Storing keys safely.
• The check still runs on every write. A key that was not revoked, such as one from a member who left before keys were revoked automatically, is refused with a 403 that says "This API key's creator is no longer a member of this organization. Ask an owner or admin to issue a new key."

A role change needs no revocation at all: if the person who created a key is demoted, the very next write through that key reflects their new role, with no propagation delay.

Reads carry the membership half of this check: a key whose creator is no longer a member of the organization gets 401 on every read, the same answer a revoked key gets. The one exception is GET /api/v1/audit-logs, which checks a key's scopes first: a key without audit:read gets the 403 that names the scope before its creator is looked at. A read doesn't check the creator's role (except on GET /api/v1/audit-logs) or whether their email address is verified.

Next steps

• Developer API - Every endpoint, with request and response shapes
• API Errors and Retries - What a refused or failed request returns, and how to retry
• Audit Logs - Where key creation, rotation and revocation are recorded