Consent management API: automate your GDPR record, stats and scans

A consent management API exposes programmatically what your CMP manages in its interface: the consent record (your GDPR proof), acceptance statistics, banner configuration and cookie scans. In practice, it lets you automatically export the proof of consent required by Article 7 of the GDPR, feed acceptance rates into your internal dashboards, and trigger a tracker scan on every production deploy — without opening the dashboard.

This automation need concerns two profiles first: agencies operating dozens of client sites who cannot click through that many interfaces, and technical teams who want compliance wired into their existing processes (CI/CD, reporting, internal tooling). For this, ConsentLab exposes a versioned public REST API (/v1), covered in our API documentation with an explorable OpenAPI reference. This guide covers what a consent API should expose, then three complete practical cases with the matching curl requests.

What a consent API is for

GDPR consent does not stop at the banner. Behind the interface, a CMP accumulates data with real operational value: every visitor choice is recorded with its timestamp (the record), aggregated choices form your acceptance statistics, and the list of trackers detected on your site evolves with every deploy.

As long as you run one site, the interface is enough. Things change with scale: an agency managing forty client sites cannot export forty records by hand every year, and a data team correlating acceptance rates with traffic will not copy numbers out of a dashboard. That is exactly what an API is for: making this data available to your scripts, your dashboards and your deployment pipeline.

A vocabulary note: the consent API discussed here is the management API (reading the record, driving configuration). It is distinct from the banner's own API, which records visitor choices — your CMP already uses that one for you.

What a consent API should expose

Four resource families cover most needs. Here is how they map to the ConsentLab API:

Authentication uses a key carried in the Authorization: Bearer header. Each key carries explicit scopes — read:consents, read:stats, read:config, write:config, trigger:scan — so you can create a strictly read-only key for a reporting tool and keep write access for a separate use. A key can also be restricted to a single site: handy for giving an end client access without exposing the rest of the portfolio.

Practical case 1: export the consent record (GDPR proof)

Article 7 of the GDPR requires you to be able to demonstrate that consent was collected. In a regulator audit or a dispute, your record — who, when, which choices — is that proof. Our article on the record of processing activities covers the documentation side; here, we automate the export.

curl -s "https://api.consentlab.eu/v1/sites/{SITE_ID}/consents?limit=100" \
  -H "Authorization: Bearer cl_live_your_key"

The response contains the records (consent identifier, choices per category, timestamp) and an opaque cursor: as long as a next_cursor is present, call the endpoint again with ?cursor= for the next page. A twenty-line script is enough to rebuild the full record and archive it wherever you want — internal vault, S3, or the attachment of a yearly email.

Why it matters: raw records are kept for five years (civil limitation period), then purged. A periodic export — yearly, for instance — builds you an archive that outlives that window. It is the reflex we recommend to every account, and the first script to write when you enable the API.

Practical case 2: feed acceptance rates into your dashboards

The acceptance rate is a steering indicator: a sudden drop often signals a banner broken by a deploy, a badly translated text, or a counter-productive design change.

curl -s "https://api.consentlab.eu/v1/sites/{SITE_ID}/consent-stats?period=30d" \
  -H "Authorization: Bearer cl_live_your_key"

The response aggregates total consents, acceptance and refusal rates, the breakdown by category (necessary, analytics, marketing) and the day-by-day evolution over the period (7d, 30d, 90d or all). Enough to feed a Grafana widget, an automated spreadsheet, or the monthly report an agency sends its clients — looping over GET /v1/sites to cover the whole portfolio.

Practical case 3: trigger a cookie scan after every production deploy

The classic non-compliance scenario: a team adds a third-party widget (chat, video, A/B testing) that drops cookies before consent — and nobody notices for months. Our cookie scanner detects those trackers; the API lets you trigger it at the right moment, i.e. right after each deploy:

curl -s -X POST "https://api.consentlab.eu/v1/sites/{SITE_ID}/scans" \
  -H "Authorization: Bearer cl_live_your_key"

The endpoint answers 202 Accepted: the scan runs in the background, and if new trackers appear compared to the previous scan, the usual email alert goes out to the site owners. Add this request as the last step of your CI/CD pipeline (GitHub Actions, GitLab CI…) with a dedicated key carrying only the trigger:scan scope: even if the key leaks in a CI log, it can neither read your record nor modify your banner.

Key security: what to demand from a consent API

An API key gives access to compliance data: its management deserves the same standards as production access. What to check — and what ConsentLab does:

• Read-only scopes for anything that does not write; the reporting key does not need write:config.
• Rate limiting: 600 requests per minute per key, with X-RateLimit-* headers so your scripts can behave properly.
• Optional lifetime (TTL) and allowed IP list per key: a CI key can expire on a fixed date and only accept your runners' IPs.
• Two-step rotation: the new key is issued while the old one stays valid during the switchover, with no service interruption.
• Automatic revocation on leaks: ConsentLab is integrated with GitHub secret scanning — a cl_live_ key committed by mistake to a public repository is detected and revoked automatically, and you are alerted.
• Call log: every request is traced (endpoint, date, response code), browsable for 90 days — useful for audits as much as debugging.

A key's secret is displayed only once at creation: store it in a secrets manager, never in plain text in code.

How to enable the ConsentLab API

The public API is included in Business plans from 500,000 sessions and Agency — see pricing. Activation happens in the dashboard, in the settings' "API" tab: key creation (scopes, site, TTL, IPs), one-time secret copy, and the call log.

Three resources to get started:

1. The API documentation: 5-minute quickstart, recipes by use case and endpoint reference.
2. The explorable OpenAPI reference at api.consentlab.eu/v1/docs (spec exportable as JSON to generate a client in your language).
3. The versioning policy: the API is versioned (/v1) with a compatibility commitment — any breaking change ships as a new version, the previous one remaining available for 12 months.

What is a consent management API? It is a programming interface exposed by a CMP to access its data and functions without the interface: consent record export, acceptance statistics, banner configuration and cookie scan triggering. It is used to automate GDPR compliance at scale, especially for multi-site agencies.

Is exporting the consent record a GDPR obligation? Article 7 of the GDPR requires being able to demonstrate that consent was collected. The timestamped record of choices is that proof. Automated export via API lets you archive it durably, including beyond the five-year retention applied to raw records.

How do you secure a consent API key? Use minimal scopes (read-only when possible), one key per use, storage in a secrets manager, and if your CMP supports it: limited lifetime, allowed IP list and interruption-free rotation. ConsentLab additionally auto-revokes keys leaked in public GitHub repositories.

Can you trigger a cookie scan from CI/CD? Yes: a POST call to the scan endpoint at the end of the pipeline starts the analysis in the background. If new trackers are detected compared to the previous scan, an alert is sent — a tracker added by a deploy is caught immediately rather than months later.

Is the ConsentLab API included in the plans? It is included at no extra cost in Business plans from 500,000 monthly sessions and in the Agency plan. Keys are created from the dashboard, and the public documentation with OpenAPI reference is accessible without an account.

Conclusion

A consent API turns your CMP into an infrastructure component: the record exports itself, acceptance rates live in your dashboards, and every deploy triggers its tracker scan. Each of the three scripts in this guide fits in a few lines — the longest part is deciding where to archive the record.

If you manage several sites, start with the GET /v1/sites loop + record export: that is the GDPR proof of your whole portfolio, automated in one go. And if your current CMP does not expose an API, it is a comparison criterion worth adding to your grid — at most vendors, this is reserved for quote-based Enterprise plans.