Skip to main content

API Reference

All endpoints below are relative to:

https://api.bytemonk.co/api/v1/public/cmp

Every request requires an X-Org-Api-Key header — see Authentication. Endpoints marked 🔒 principal token additionally require an X-Principal-Token header identifying which data principal the request acts on behalf of — there is no principalId/externalId field to supply in the body for these; the principal is derived entirely from the token.

There's also a second, separate base path for server-to-server integrations — https://api.bytemonk.co/api/v1/server/cmp — covered in Server-Side Integration, not in the table below. It has two endpoints: POST /principals/token (Mode B token issuance) and POST /principals/rotate-secret (mint a fresh principalSecret for an existing externalId — see Rotate principalSecret).

Endpoint index​

MethodPathPurposeAuth
POST/principals/registerRegister or resolve a data principalOrg key
POST/principals/tokenExchange a principalSecret for a session tokenOrg key
POST/guardian/registerRegister a guardian for a minor principal🔒 principal token
GET/guardian/statusCheck a minor's own guardian record's verification status🔒 principal token
POST/principals/token/revokeInvalidate the current session token ahead of its natural expiry🔒 principal token
GET/noticeFetch the currently active notice for a groupKey/languageOrg key
GET/notice/{id}Fetch a specific (possibly superseded) notice by idOrg key
POST/consent/grantRecord a principal's purpose-level consent🔒 principal token
POST/consent/withdrawWithdraw a previously granted consent🔒 principal token
GET/consent/statusCheck a principal's current consent status for a notice🔒 principal token
GET/consent/recordsList a principal's current consent state across every notice🔒 principal token
POST/dsrSubmit a Data Principal Request (DPR)🔒 principal token
GET/dsr/status/{referenceId}Check a DSR request's status🔒 principal token
GET/dsrList a principal's DSR request history🔒 principal token
POST/grievancesFile a grievance🔒 principal token
GET/grievances/status/{referenceId}Check a grievance's status🔒 principal token
GET/grievancesList a principal's grievance filing history🔒 principal token

Conventions​

  • All request/response bodies are application/json.
  • Every response is wrapped in the same envelope, described in Error Codes — { entity, warnings, errors, success }.
  • Datetimes are ISO-8601 with timezone offset, e.g. "2026-07-04T04:47:50.649+00:00".
  • IDs (noticeId, etc.) are numbers, not strings. Principal identity is never passed as a field — see the 🔒 principal token column above.
  • Every endpoint returns/accepts a single resource except the three "list mine" endpoints (GET /dsr, GET /grievances, GET /consent/records), which are paginated the same way the admin API is — ?page=0&size=20 query params, response entity shaped like { content: [...], number, size, totalElements }. These are scoped strictly to the calling X-Principal-Token's own principal — there's no way to list another principal's records, or list across all principals (that's admin-facing only).