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

## Authenticating as an AI agent

AI agents authenticate the same way as any other server-to-server integration: an API key in the `X-API-Key` header. There is no separate agent credential type. A machine-readable version of this walkthrough is published at [politicalcomms.com/auth.md](https://politicalcomms.com/auth.md).

<Steps>
  <Step title="Have a human operator provision the key">
    Key creation is not an API operation. A human operator generates the key in the dashboard under **Admin → API**, copies it (it is shown only once), and provisions it to the agent through a secret manager or environment variable. Keys never belong in prompts, code, or version control.
  </Step>

  <Step title="Send the key on every request">
    Pass the key in the `X-API-Key` header on every request to `https://api.politicalcomms.com/v1`.

    ```http theme={null}
    X-API-Key: pc_live_1234567890abcdef
    ```
  </Step>

  <Step title="Verify the credential">
    Confirm the key works with a read-only call before doing anything else. `GET /organizations` has no side effects and returns the organizations the key can access.

    <CodeGroup>
      ```bash curl theme={null}
      curl https://api.politicalcomms.com/v1/organizations \
        -H "X-API-Key: $POLCOMMS_API_KEY"
      ```
    </CodeGroup>

    A `200` response with `"success": true` means the key is valid and scoped correctly.
  </Step>

  <Step title="Handle 401 and 429 responses">
    * `401` means the key is missing, malformed, or revoked. Do not retry. Surface the failure to the operator so they can issue a new key. See [Errors](/api-reference/errors).
    * `429` means the key hit its rate limit (600 requests per minute per key). Read the `Retry-After` header and back off for that many seconds before retrying. See [Rate Limits](/api-reference/rate-limits).
  </Step>

  <Step title="Verify webhook deliveries">
    Webhook payloads are HMAC-SHA256 signed. Validate the `X-Webhook-Signature: sha256=...` header before trusting any payload. See [Signature validation](/api-reference/webhooks/signature-validation).
  </Step>
</Steps>

<Note>
  Platform status is published at [status.politicalcomms.com](https://status.politicalcomms.com). Check it before treating repeated failures as a credential problem.
</Note>

## Machine-to-machine (M2M) authentication

API keys are the machine-to-machine credential for the Political Comms API. Any unattended integration, whether a cron job, a backend service, a service account, or an autonomous AI agent, authenticates the same way: a `pc_live_` key in the `X-API-Key` header.

There is no OAuth 2.0 client credentials grant, no token endpoint, and no dynamic client registration. Do not attempt an OAuth flow against `api.politicalcomms.com`; it does not exist. The API also does not publish `/.well-known/oauth-authorization-server` or `/.well-known/oauth-protected-resource` metadata.

Treat one dedicated key per agent or service as the service account for that integration, so it can be rotated or revoked independently of everything else. A step-by-step programmatic walkthrough for agents is published at [politicalcomms.com/auth.md](https://politicalcomms.com/auth.md), with a matching error recovery playbook at [politicalcomms.com/errors.md](https://politicalcomms.com/errors.md).

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.