Skip to main content

​
Overview

Pwnbook API authentication uses API keys. API keys are long-lived credentials scoped to an organization with fine-grained permission scopes. Every API request must include a valid API key in the Authorization header.

​
Generating an API key

API keys are created per organization. You need Admin or Owner access to generate an API key.
1

Open organization settings

Go to Organization Settings → API Keys.
2

Create a new key

Click New API Key.Enter a descriptive name for the key. Choose a name that identifies what it will be used for, such as “CI Pipeline”, “SIEM Integration”, or “Custom Dashboard”.
3

Select scopes

Choose the permission scopes for this key. Select only the scopes needed for the key’s intended purpose (principle of least privilege).See Scopes and permissions below for a full list.
4

Copy the key

After clicking Create, the full API key is displayed once. Copy it and store it securely (a password manager or secrets manager).
The full API key value is only shown at creation time. If you lose it, you’ll need to delete the key and create a new one. Pwnbook never displays the full key again after the initial creation.

​
Using API keys in requests

Include the API key in the Authorization header of every request: 
GET /api/v1/engagements
Authorization: Bearer pwbk_live_abc123def456...
Content-Type: application/json
API keys always start with pwbk_live_ for production keys and pwbk_test_ for test keys.

​
Example with curl

curl https://app.pwnbook.io/api/v1/engagements \
  -H "Authorization: Bearer pwbk_live_abc123def456..." \
  -H "Content-Type: application/json"

​
Example with JavaScript (fetch)

const response = await fetch('https://app.pwnbook.io/api/v1/engagements', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer pwbk_live_abc123def456...',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

​
Example with Python (requests)

import requests

headers = {
    'Authorization': 'Bearer pwbk_live_abc123def456...',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://app.pwnbook.io/api/v1/engagements',
    headers=headers,
)

data = response.json()

​
Scopes and permissions

API keys are restricted to the scopes selected at creation time. Attempting an action not covered by the key’s scopes returns a 403 Forbidden response.

​
Available scopes

ScopeDescription
engagements:readList and read engagement details
engagements:writeCreate, update, and archive engagements
engagements:deleteDelete engagements
targets:readRead recon targets and scan results
targets:writeAdd and update targets, trigger scans
tasks:readRead tasks across engagements
tasks:writeCreate, update, and close tasks
wiki:readRead wiki pages
wiki:writeCreate and edit wiki pages
reports:readRead generated reports
reports:writeCreate and update reports
organizations:readRead organization details and member list
organizations:writeUpdate organization settings, invite members
api-requests:readRead saved API requests
api-requests:writeCreate and execute API requests
Use caseRecommended scopes
Read-only dashboard integrationengagements:read, tasks:read, reports:read
CI/CD pipeline integrationengagements:read, targets:write, tasks:write
Report automationengagements:read, reports:read, reports:write, wiki:read
Full automationAll scopes relevant to your use case

​
Viewing and managing API keys

To view all API keys for your organization:
  1. Go to Organization Settings → API Keys.
  2. The list shows all keys with their names, scopes, creation date, and last-used timestamp.
You can see when a key was last used to identify unused or orphaned keys.

​
Rotating API keys

To rotate an API key:
  1. Generate a new API key with the same scopes as the key being rotated.
  2. Update your integration to use the new key.
  3. Verify the integration is working with the new key.
  4. Delete the old key from Organization Settings → API Keys.
There is no in-place rotation — you create a new key and delete the old one. This ensures you always know what credentials are in use.

​
Revoking API keys

To immediately invalidate an API key:
  1. Go to Organization Settings → API Keys.
  2. Click the … menu next to the key.
  3. Select Delete Key.
  4. Confirm the deletion.
The key is invalidated instantly. Any requests using the deleted key will receive a 401 Unauthorized response.

​
Security best practices

  • Never commit API keys to version control. Use environment variables or a secrets manager.
  • Use the minimum required scopes. Don’t grant engagements:delete to a key that only needs to read data.
  • Rotate keys regularly. Especially for long-lived integrations, rotate keys every 90 days.
  • Monitor last-used timestamps. Delete keys that haven’t been used in 30+ days.
  • Use separate keys per integration. This makes it easy to revoke a single integration without affecting others.