Supported Integrations

Integrate with the POPIASAFE compliance platform using Public API v1, webhooks, and manual data workflows.

1. Scope and purpose

This guide is for developers and technical implementers connecting POPIASAFE to CRMs, consent workflows, reporting stacks, and internal platforms.

2. Supported integration methods

Public API v1 over HTTPS (`/api/v1`)
Outbound webhooks for real-time events
Manual CSV export/import for operational workflows

3. Authentication

Use API keys from Settings → Developers with header Authorization: Bearer psk_<key>. Webhooks can use a shared secret with `X-PopiaSafe-Signature`.

4. Event types

consent.created
consent.granted
consent.withdrawn
consent.expired
developers.test

5. Rate limits and quotas

API usage is quota-controlled by plan and billing period. Exceeded usage returns HTTP 429 with `QUOTA_EXCEEDED` and retry guidance.

6. Retry behaviour and backoff

For 429/5xx responses, use exponential backoff and honor `Retry-After`. POPIASAFE webhook deliveries also retry transient failures with backoff.

7. Error model

Errors return a consistent schema with `success`, `error.code`, `error.message`, `requestId`, and `timestamp`. Common codes include `INVALID_API_KEY`, `NOT_FOUND`, and `QUOTA_EXCEEDED`.

8. SLA and operational expectations

POPIASAFE targets high availability and communicates planned maintenance. Use `requestId` when contacting support about integration incidents.

9. Security notes

HTTPS only for API and webhooks
Treat API keys as secrets and rotate regularly
Verify webhook signatures before processing payloads

10. Change and versioning policy

Current version is Public API v1 at `/api/v1`. Breaking changes are released under a new major version and communicated in advance.