API keys

API keys let scripts, dashboards and CI jobs call the Public REST API (v1) without a user session. A key belongs to the organization, not to the person who created it.

Who can use this: Org admin only. See Roles.

AvailabilityCopy Anchor Link

API keys need a plan with API access:

Only an Org admin can see and manage keys. Organization > API keys does not appear on Free or Team; upgrade to Business to see it.

The exception is a CI key: a key that holds only the write:ci scope can be created on every plan. Free and Team organizations can have up to 5 of them, and the page opens for that purpose. See CI keys.

Create a keyCopy Anchor Link

1. Open Organization > API keys.
2. Click Create key.
3. Enter a Name (1 to 64 characters), for example "CI pipeline dashboard".
4. Pick at least one scope.
5. Pick when it Expires: 30 days, 90 days (the default), 1 year or no expiry.
6. Click Create key and copy the key.

The full key is shown once. Store it in a secret manager; it cannot be recovered. If you lose it, revoke it and create a new one.

ScopesCopy Anchor Link

Give a key only the scopes it needs.

A key with write:ai-telemetry or write:ci must have no other scope. Make one such key for each source. See Claude Code telemetry and CI keys.

Scopes are fixed when the key is created. To change them, create a new key.

A key with write:deployments must always give a reason of 10 to 500 characters, and cannot answer GitHub required-reviewer gates, which need a person's own GitHub account.

Overriding compliance blocksCopy Anchor Link

When a Block compliance policy covers the environment, answering Prodgator's protection rule overrides a compliance decision. A key needs both write:deployments and write:compliance-override to do that. A key with only write:deployments gets 403 insufficient_scope and nothing is sent to the provider. The same applies when Prodgator cannot read the compliance policies at that moment. write:compliance-override on its own allows nothing.

Add write:compliance-override only to keys that must release past a compliance block, such as an emergency release job. Each override is written to the audit log under the key's name, with its reason.

CI keysCopy Anchor Link

A write:ci key lets a pipeline in CircleCI, Buildkite, Jenkins or another CI system send runs, reports, attestations and artifacts, and open release gates, through the prodgator-report command line or the /v1/ci API. See Any CI.

• It holds no other scope. It cannot read data and cannot approve a deployment, even one it opened.
• It is available on every plan, and does not need API access. A Free or Team organization can have up to 5 CI keys.
• What it sends is self-reported: policies ignore it unless a rule opts in, and it never counts as provider provenance.
• The Repositories field is an allowlist of host/path patterns, for example github.com/acme/* (up to 50). * stands for any characters inside one path segment and never crosses /. A run for any other repository is refused with repository_not_allowed. The check is made when the run is created, and later calls follow the run. Leave it empty to allow every repository, which Prodgator does not recommend.
• Use a 90-day expiry or shorter and keep the key out of builds of forked pull requests. The CLI reads it only from an environment variable.

An OIDC trust is the better choice when your CI system issues tokens: there is no long-lived secret. See Integrations.

Key formatCopy Anchor Link

Keys start with plk_live_ in production and plk_test_ in development. A key only works in the environment that issued it.

Using a keyCopy Anchor Link

Send the key as a bearer token:

curl -s \
  -H "Authorization: Bearer $PRODGATOR_API_KEY" \
  "https://api.prodgator.io/v1/runs?status=failure&limit=25"

Requests are rate limited. Retry 429 responses with backoff.

Revoke a keyCopy Anchor Link

In Organization > API keys, click revoke on the key's row and confirm with Revoke key. Requests using it start failing within about a minute. Revoking cannot be undone.

Expired keys still count toward your plan's key limit until you revoke them. The page shows how many of your allowed keys are in use.

API explorerCopy Anchor Link

The API explorer is an interactive client inside Prodgator for calling the v1 API. It uses the public v1 API reference, shows each operation's docs next to the request builder, and completes JSON request bodies from the schema.

Who can use this: Every member on a plan with API access, viewers included.

Read scopes: The explorer offers the read scopes your session can access: read:pipelines, read:deployments, read:security, read:compliance, and read:attestations when your plan includes attestations.

Sessions and tokens: Each session uses an explorer token that lasts 15 minutes and is kept only in the page's memory, never stored. Tokens are bound to your organization and the app's origin and carry only the scopes you pick. Click Renew in the last 2 minutes to extend the session and get a new token.

Revocation: You can end a session any time by clicking End session. Switching organization or signing out revokes it automatically. Closing the page also ends the session, but only on a best effort basis (the browser may not finish the request), so the 15 minute limit always applies. An org admin can revoke any member's explorer session from the Explorer sessions card on the Keys tab.

Sessions also end when your membership is removed or suspended, or when your organization's SSO policy changes. A revocation can take up to a minute to take effect.

Limitations: The API explorer is read-only in this release. All spec text appears in English.

Try the API explorerCopy Anchor Link

1. Go to Organization > API keys > Explorer.
2. Leave the scopes you need ticked and click Start session.
3. Select an operation from the list, fill any required parameters, and click Send.
4. Read the response. To run the same call from a terminal, copy the curl command and set PRODGATOR_API_KEY to an API key of your own; the explorer token is never shown.