Skip to main content
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.

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

​
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: See the 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.
1

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 Keys, 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.
2

Send the key on every request

Pass the key in the X-API-Key header on every request to https://api.politicalcomms.com/v1.
3

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.
A 200 response with "success": true means the key is valid and scoped correctly.
4

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.
  • 429 means the key hit its rate limit (100 requests per minute per key). Read the Retry-After header and back off for that many seconds before retrying. See Rate Limits.
5

Verify webhook deliveries

Webhook payloads are HMAC-SHA256 signed. Validate the X-Webhook-Signature: sha256=... header before trusting any payload. See Signature validation.
Platform status is published at status.politicalcomms.com. Check it before treating repeated failures as a credential problem.

​
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, with a matching error recovery playbook at 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.