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

# Authentication

> API keys, the X-API-Key header, scoping to your organization hierarchy, and how to keep secrets safe.

Authenticate every request by passing your API key in the `X-API-Key` header. Keys are scoped to your organization hierarchy - you can only access your own data and the data of any descendant organizations.

```http theme={null}
X-API-Key: pc_live_1234567890abcdef
```

## Issuing and rotating keys

1. From the dashboard, go to **Admin → API Keys**.
2. Click **New Key**. Give it a descriptive name (e.g. "Production CRM sync", "Staging analytics export"). The key is shown only once - copy it immediately and store it in a secret manager.
3. To rotate, generate a new key, swap it into your deployed apps, verify traffic on the new key, then revoke the old one.
4. To revoke compromised keys, click **Revoke** - the key stops working immediately.

<Warning>
  **Store API keys in environment variables or secret management systems.** Never commit keys to version control or ship them in client-side code. Rotate regularly; revoke compromised keys immediately.
</Warning>

## Scoping

API keys are scoped to your organization's hierarchy. A key issued at the parent organization can read data from all descendant organizations; a key issued at a sub-org can only read data within that sub-org and its descendants. Cross-tree access is never possible.

Errors you'll see if scoping blocks a request:

| Code                | Meaning                                                                  |
| ------------------- | ------------------------------------------------------------------------ |
| `INVALID_API_KEY`   | Key is missing, malformed, or has been revoked.                          |
| `ORG_ACCESS_DENIED` | The `organization_id` you requested is not in your accessible hierarchy. |
| `PERMISSION_DENIED` | Your key is valid but lacks the permission scope this endpoint requires. |

See the [Errors](/api-reference/errors) page for the full list of error codes.

## Per-key best practices

* **Separate keys per environment.** Production, staging, and local dev should have distinct keys.
* **Separate keys per integration.** Your CRM sync, your analytics export, and your internal admin tool should each have their own key. If one is compromised you can revoke it without breaking the others.
* **Audit usage.** The dashboard shows request counts and last-used timestamps per key. Investigate keys that haven't been used in 30+ days - they're often candidates for deletion.

## What about user authentication?

API keys are for **server-to-server** integrations. End-user (dashboard) authentication is handled separately via JWT in the Political Comms application and is not exposed through this API. If you're building a customer-facing app that needs to act as a specific user, contact support to discuss OAuth-based options.