Skip to content

api-keys.mdx

Latest commit

 

History

History
148 lines (107 loc) · 3.55 KB

api-keys.mdx

File metadata and controls

148 lines (107 loc) · 3.55 KB
Raw
title API Keys
icon KeyRound
description Create, rotate, and revoke PgBeam API keys for programmatic access.

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 
<Callout type="warn" title="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.
</Callout>

Use an API key

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

<Tabs items={["curl", "JavaScript", "Python", "CLI"]}> bash curl -H "Authorization: Bearer pbo_..." https://api.pgbeam.com/v1/projects

```ts const response = await fetch("https://api.pgbeam.com/v1/projects", { headers: { Authorization: `Bearer ${process.env.PGBEAM_API_KEY!}`, }, }); ``` ```python import requests import os 
response = requests.get(
    "https://api.pgbeam.com/v1/projects",
    headers={"Authorization": f"Bearer {os.environ['PGBEAM_API_KEY']}"},
)
```
```bash # 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.