Agency guide
API Keys & Webhooks
Create named API keys scoped to specific permissions and configure webhooks to receive real-time policy events for your entire agency workspace.
API keys
Agency API keys are prefixed pak_live_ and can be created with fine-grained scopes. Navigate to Agency Hub → API & Webhooks to manage them.
Creating a key
Name your key
Use a descriptive name like "CRM integration" or "Zapier automation" so team members know what each key is for.
Choose scopes
Select only the permissions your integration needs. Unused scopes increase attack surface.
Optionally restrict to a client
Client-scoped keys can only generate or read policies for a single client site.
Copy the key immediately
The full key is shown only once at creation time. Store it in a secrets manager immediately.
Available scopes
| Scope | Allows |
|---|---|
| policies:read | List and retrieve policy content |
| policies:write | Generate and update policies |
| policies:delete | Delete policies permanently |
| clients:read | List clients and their metadata |
| clients:write | Create and update clients |
| webhooks:read | List configured webhooks |
| webhooks:write | Create, update, and delete webhooks |
| members:read | List team members and their roles |
Team member access
Team members with the Admin role can create and manage API keys. Editor and Viewer roles cannot access API key management. Keys created by a member are agency-wide unless client-scoped.
Rotating keys
To rotate a key: create a new key → update your integration → delete the old key. There is no in-place rotation — deleting a key immediately revokes it. Use the key name to track which system uses which key.
Using the API key
Pass the key as a Bearer token in every request:
curl https://policifyai.com/api/v1/policies \ -H "Authorization: Bearer pak_live_your_key_here"
The base URL for all API calls is https://policifyai.com/api/v1. See the full API reference for endpoints.
Webhooks
Webhooks send a POST request to your endpoint whenever a policy event occurs across your agency workspace. Events include policy creation, updates, deletions, and views.
Creating a webhook
Your HTTPS endpoint that will receive events. Must return 2xx within 10 seconds.
Select: policy.created, policy.updated, policy.deleted, policy.viewed (or all).
Optionally restrict events to a single client site.
Auto-generated; used to verify the X-PolicifyAI-Signature header.
Verifying the signature
Every delivery includes an X-PolicifyAI-Signature header — an HMAC-SHA256 of the raw request body, keyed with your webhook secret. Always verify this before processing.
// Node.js
const crypto = require('crypto')
function verifySignature(payload, secret, header) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.digest('hex')
return header === expected
}Retries & failures
If your endpoint does not return 2xx within 10 seconds, PolicifyAI retries up to 5 times with exponential backoff (30 s, 2 min, 10 min, 30 min, 2 h). After 5 failures the webhook is automatically disabled and you receive an email.