> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pwnbook.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API Authentication

> Learn how to generate API keys, use them in requests, manage scopes and permissions, and rotate keys securely.

## 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.

<Steps>
  <Step title="Open organization settings">
    Go to **Organization Settings** → **API Keys**.
  </Step>

  <Step title="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".
  </Step>

  <Step title="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](#scopes-and-permissions) below for a full list.
  </Step>

  <Step title="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).

    <Warning>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.</Warning>
  </Step>
</Steps>

## Using API keys in requests

Include the API key in the `Authorization` header of every request:

```http theme={null}
GET /api/v1/organizations/current
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

```bash theme={null}
curl https://your-pwnbook-domain.com/api/v1/organizations/current \
  -H "Authorization: Bearer pwbk_live_abc123def456..." \
  -H "Content-Type: application/json"
```

### Example with JavaScript (fetch)

```javascript theme={null}
const response = await fetch('https://your-pwnbook-domain.com/api/v1/organizations/current', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer pwbk_live_abc123def456...',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
```

### Example with Python (requests)

```python theme={null}
import requests

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

response = requests.get(
    'https://your-pwnbook-domain.com/api/v1/organizations/current',
    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

| Scope                 | Description                                  |
| --------------------- | -------------------------------------------- |
| `targets:read`        | Read recon targets and scan results          |
| `targets:write`       | Add and update targets, trigger scans        |
| `tasks:read`          | Read tasks                                   |
| `tasks:write`         | Create, update, and close tasks              |
| `wiki:read`           | Read wiki pages                              |
| `wiki:write`          | Create and edit wiki pages                   |
| `organizations:read`  | Read organization details and member list    |
| `organizations:write` | Update organization settings, invite members |
| `api-requests:read`   | Read saved API requests                      |
| `api-requests:write`  | Create and execute API requests              |

### Recommended scopes by use case

| Use case                        | Recommended scopes                   |
| ------------------------------- | ------------------------------------ |
| Read-only dashboard integration | `tasks:read`, `organizations:read`   |
| CI/CD pipeline integration      | `targets:write`, `tasks:write`       |
| Wiki automation                 | `wiki:read`, `wiki:write`            |
| Full automation                 | All 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 write scopes 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.