# Authenticating with the Political Comms API

This is the credential walkthrough for agents and services integrating with the Political Comms REST API. The human-readable reference lives at https://docs.politicalcomms.com/api-reference/authentication and the OpenAPI 3.1 specification at https://politicalcomms.com/openapi.json (mirror: https://docs.politicalcomms.com/api-reference/openapi.json).

## Discover

- API base URL: `https://api.politicalcomms.com/v1`
- OpenAPI 3.1 specification: https://politicalcomms.com/openapi.json (the `securitySchemes` block defines `ApiKeyAuth`, an `apiKey` scheme in the `X-API-Key` header)
- This API does not publish `/.well-known/oauth-protected-resource` or `/.well-known/oauth-authorization-server` metadata, and there is no `agent_auth` block with a `register_uri`. Those documents do not exist because the API does not use OAuth. Do not probe for them.

## Pick a method

There is exactly one method: API keys.

API keys are the machine-to-machine (M2M) credential for this API. Any unattended integration, whether a cron job, a backend service, a service account, or an autonomous AI agent, authenticates the same way: a key passed in the `X-API-Key` request header. There is no OAuth 2.0 client credentials grant, no token endpoint, no dynamic client registration, no identity assertion flow, and no anonymous access. A dedicated API key is the service account for an agent: issue one key per agent so it can be rotated or revoked independently.

Keys are prefixed `pc_live_` and are shown exactly once at creation.

```
X-API-Key: pc_live_1234567890abcdef
```

## Register

Key creation is a human-initiated operation. It is not available over the API.

1. A workspace administrator signs in at https://app.politicalcomms.com/
2. Navigate to Admin, then API Keys.
3. Create a key. Name it for the integration it serves, one key per agent or service.

Keys are scoped to the organization hierarchy they are created in. A key issued at a parent organization can read data from all descendant organizations; cross-tree access is never possible.

## Claim

The full key value is displayed once at creation. Store it in a secret manager and provision it to your agent or service through the secret manager or an environment variable. Never embed keys in code, prompts, or repositories.

## Use the credential

Verify a credential with a read-only request:

```
curl https://api.politicalcomms.com/v1/organizations \
  -H "X-API-Key: $POLITICAL_COMMS_API_KEY"
```

A `200` with a JSON body confirms the key is live. Send the key on every request; the base URL for all endpoints is `https://api.politicalcomms.com/v1`.

## Errors

Errors return structured JSON with the shape `{ "success": false, "error": "...", "code": "...", "statusCode": ... }`.

- `401` means the key is missing, malformed, or revoked. Do not retry with the same credential. Surface the failure to a human operator so they can issue a new key.
- `429` means the rate limit is exhausted. Limits are per key over a 60-second sliding window: 100 requests/minute for reads, 60/minute for writes, 30/minute for deletes. Read the `X-RateLimit-Remaining` and `X-RateLimit-Reset` response headers and back off until the reset window.
- `5xx` responses are safe to retry with exponential backoff. Write operations accept an `Idempotency-Key` header so retries cannot double-apply.

Full recovery playbook: https://politicalcomms.com/errors.md. Reference: https://docs.politicalcomms.com/api-reference/errors and https://docs.politicalcomms.com/api-reference/rate-limits. Platform status: https://status.politicalcomms.com

## Revocation

Rotate keys from the same dashboard surface (Admin, then API Keys): create the replacement, swap it into the deployment, verify traffic, then revoke the old key. Revoked keys fail immediately with `401`.

## Webhooks

Webhook deliveries are signed with HMAC-SHA256 in the `X-Webhook-Signature` header (`sha256=...`). Validate the signature before trusting any payload. Verification guide: https://docs.politicalcomms.com/api-reference/webhooks/signature-validation

## Related machine-readable surfaces

- OpenAPI specification: https://politicalcomms.com/openapi.json
- Error recovery playbook: https://politicalcomms.com/errors.md
- MCP server (documentation search): https://docs.politicalcomms.com/mcp
- Site index for agents: https://politicalcomms.com/llms.txt
- Full reference corpus: https://politicalcomms.com/llms-full.txt
- Pricing: https://politicalcomms.com/pricing.md