API Keys

API keys authenticate programmatic access to the PgBeam REST API and CLI.

Key types

PgBeam supports two types of API keys:

Type	Prefix	Scope	Manage in
Personal keys	`pbu_`	All your organizations	Settings > Account > API Keys
Organization keys	`pbo_`	Single organization	Settings > Organization > API Keys

Use organization keys for CI/CD and shared automation. Use personal keys for your own tools and scripts.

Create an API key

Navigate to API Keys

From the dashboard, go to Settings and select the relevant API Keys page (Account or Organization level).

Create the key

Click Create Key and configure:

Name — A label to identify the key (e.g., "CI/CD", "monitoring", "staging deploy")
Expiry — Optional. Choose 30 days, 90 days, 365 days, or no expiry.

Copy the key

Copy immediately

The full key is shown only once after creation. Copy it immediately and store it securely. You cannot retrieve the full key after closing the dialog.

Use an API key

Pass the key in the Authorization header as a bearer token:

curl -H "Authorization: Bearer pbo_..." https://api.pgbeam.com/v1/projects

const response = await fetch("https://api.pgbeam.com/v1/projects", {
  headers: {
    "X-API-Key": process.env.PGBEAM_API_KEY!,
  },
});

import requests
import os

response = requests.get(
    "https://api.pgbeam.com/v1/projects",
    headers={"X-API-Key": os.environ["PGBEAM_API_KEY"]},
)

# Authenticate once
pgbeam auth login --api-key
# Paste your API key when prompted

# Or use an environment variable
export PGBEAM_TOKEN=pbu_...
pgbeam projects list

Rotate a key

Create a new key

Generate a new key with the same permissions as the one you want to rotate.

Update your application

Update your application, CI/CD pipeline, or scripts to use the new key.

Verify the new key

Confirm the new key works correctly in all environments.

Revoke the old key

Delete the old key from Settings > API Keys. Revoked keys stop working immediately.

Security best practices

Store keys in environment variables or a secret manager — never commit them to source control.
Set an expiry for keys used in CI/CD or automation.
Use separate keys for different environments (production, staging, development).
Use organization keys for shared automation so revoking a team member's access does not break CI/CD.
Revoke keys immediately if they may have been exposed.
Audit key usage — review active keys periodically and revoke any that are no longer needed.

On this page