PXL Consent

REST API

Everything the dashboard does with sites, banners, scans and consent records is available over a REST API with JSON bodies.

Authentication

Create an API key under Organisation → API keys (admins only). The key is shown once. Send it as a bearer token:

curl -H "Authorization: Bearer ccs_…" https://consent.pxl.as/api/v1/organizations/42/sites

A key acts with admin rights, and cannot be used for account operations (passwords, passkeys, two-factor) or for anything that grants access or sends data elsewhere: creating API keys, inviting or changing members, changing billing details, and adding or changing notification channels. Those need a signed-in person, so a leaked key cannot outlive its revocation. A key also never sees webhook signing secrets. Revoke one from the same page; requests with it fail immediately.

Which organisation a request is for

Every organisation-scoped route names its organisation in the path:

POST /api/v1/organizations/42/sites
GET  /api/v1/organizations/42/sites/7/domains

Your organisation's id is in GET /api/v1/auth/me, which also lists the other organisations you belong to. Read it once and keep it.

Routes about an account rather than an organisation keep their own paths: /api/v1/auth/… for signing in, passkeys and the second factor. They are the same whoever you are working for.

Acting for a client

An agency can run its clients through the API with a single key, which is what a hosting platform or a reseller needs. Choose This organisation and its clients when creating the key; the option appears only on a plan that has client organisations.

Then create the client, and work inside it by naming it in the path:

# Create the client organisation, in your own.
POST /api/v1/organizations/42/agency/clients
     {"name": "Kunde AS"}
  → {"id": 98, …}

# Everything after that happens in the client.
POST /api/v1/organizations/98/sites
POST /api/v1/organizations/98/sites/7/domains
POST /api/v1/organizations/98/sites/7/config/publish

The site belongs to the client, and the client's own plan governs its limits. Each action is recorded in the client's audit log, naming the agency that performed it.

A key scoped to its own organisation only is refused with 403 KEY_SCOPE if it names another. An organisation that is not one of your clients answers 404, exactly as one that does not exist would: the API will not tell you which organisation ids are real.

A key can never create another key, so an agency key cannot issue credentials inside a client. Give a client its own access, if they should have it, by inviting a person to their organisation.

Reference

The full, generated reference with every operation and schema is at /api/v1/docs, and the OpenAPI document at /api/v1/openapi.json.

Common tasks

{org} below is the organisation the work is for: your own, or a client of yours.

TaskRequest
Create a sitePOST /api/v1/organizations/{org}/sites
Register a domainPOST /api/v1/organizations/{org}/sites/{id}/domains
Verify a domainPOST /api/v1/organizations/{org}/sites/{id}/domains/{domain_id}/verify
Publish a bannerPOST /api/v1/organizations/{org}/sites/{id}/config/publish
Start a scanPOST /api/v1/organizations/{org}/sites/{id}/scans
All sites at a glanceGET /api/v1/organizations/{org}/portfolio
Create a client organisationPOST /api/v1/organizations/{org}/agency/clients
Look up a consent IDGET /api/v1/organizations/{org}/sites/{id}/consents/{consent_id}
Export consent recordsGET /api/v1/organizations/{org}/sites/{id}/consents/export.csv?from=…&to=…

Errors

Errors use HTTP status codes with a JSON body listing each error's code and message. Plan limits answer 402 with PLAN_LIMIT or PLAN_FEATURE; a banner that fails the publish checks answers 422 with the findings; a key asked to leave its own organisation answers 403 with KEY_SCOPE.