Upgrade Guide: Consent Management APIs (v4 Migration)
cidaas v4 introduces a redesigned Consent Management service. The legacy service exposed consent management and tracking endpoints under /consent-management-srv/v2/*; the v4 service provides a unified, GDPR-first API under /consent-srv/*.
This guide outlines architectural changes, provides a comprehensive endpoint and data model mapping, details customer-actionable error handling, and provides a step-by-step migration checklist for developers and integrators.
This guide applies to developers and integrators who directly invoke cidaas Consent Management REST APIs (such as programmatically creating consents, defining localized versions, recording user acceptance, or retrieving audit history). If you manage consents exclusively through the cidaas Admin Dashboard or Trustdesk UI, no migration steps are required.
Overview of Key Changes
| Dimension | Legacy Service (/consent-management-srv/v2/*) | v4 Service (/consent-srv/*) |
|---|---|---|
| Base Path | /consent-management-srv/v2/* | /consent-srv/* |
| Data Hierarchy | Group → Instance → Version → Separate Locales | Group → Instance → Version (with embedded localized content array) |
| Legal Basis | Not explicitly modelled | Explicit GDPR Article 6 legalType (consent, contract, legal_obligation, etc.) |
| UI Presentation | Instance action_type (LOGIN/REGISTER) | interactionMode enum governing display and consent mechanics |
| Data Subject Rights | Not supported via API | First-class catalog under /consent-srv/datasubjectright |
| Version Assignment | Client-supplied integer | Server-assigned, auto-incremented integer |
| Data Retention | Not configurable | Configurable retentionPeriod per version (default: 36 months, max: 120 months) |
| Tracking Model | Separate usage tables and verification endpoints | Unified tracking records submitted via POST /consent-srv/actions |
1. Core Concept and Schema Changes
1.1 GDPR Legal Basis (legalType)
In cidaas v4, every consent instance requires a defined legal basis under GDPR Article 6:
legalType Value | Description | GDPR Reference |
|---|---|---|
consent | Explicit user consent | Article 6(1)(a) |
contract | Performance of a contract | Article 6(1)(b) |
legal_obligation | Compliance with a legal obligation | Article 6(1)(c) |
vital_interests | Protection of vital interests | Article 6(1)(d) |
public_authority | Exercise of official authority or public interest | Article 6(1)(e) |
legitimate_interests | Pursuit of legitimate interests | Article 6(1)(f) |
1.2 Interaction Modes (interactionMode)
The legacy instance-level action_type (LOGIN, ACTION, REGISTER) is removed. In v4, how the legal basis is presented and handled in the UI is defined by the interactionMode enum on the consent instance.
Allowed values (normalized to uppercase SNAKE_CASE):
EXPLICIT_OPT_IN: User must actively tick a checkbox or confirm opt-in.EXPLICIT_ACK_SCREEN: Dedicated acknowledgment screen requiring positive user action.ACKNOWLEDGED_ACK_SCREEN: Information screen requiring acknowledgment before continuing.ACKNOWLEDGED_NOTICE_BANNER: Informational banner with an explicit dismissal or accept button.IMPLICIT_NOTICE_BANNER: Non-blocking informational banner displayed during user flow.IMPLICIT_SILENT: Background recording of legal basis without UI prompt.
Allowed Interaction Modes per Legal Type:
legalType | Permitted interactionMode Values |
|---|---|
consent | All 6 values (EXPLICIT_OPT_IN, EXPLICIT_ACK_SCREEN, ACKNOWLEDGED_ACK_SCREEN, ACKNOWLEDGED_NOTICE_BANNER, IMPLICIT_NOTICE_BANNER, IMPLICIT_SILENT) |
contract, legitimate_interests | All values except IMPLICIT_NOTICE_BANNER and IMPLICIT_SILENT |
legal_obligation, vital_interests, public_authority | ACKNOWLEDGED_ACK_SCREEN or ACKNOWLEDGED_NOTICE_BANNER only |
interactionMode: "IMPLICIT_SILENT" cannot be used when showInRegistration: true. If a consent is configured to appear during user registration, an interactive or visible mode must be selected.
1.3 Version-Level Content Type and Embedded Locales
In v4, consentType belongs exclusively to the consent version, not the instance. It specifies the format of the consent content:
URL: External link to terms, conditions, or policy document.TEXT: Plain text or HTML markdown content displayed directly in the user interface.SCOPES: Dynamic authorization scopes requested as part of the consent agreement.
Embedded Localization
Instead of making separate calls to /v2/consent/locale to populate translations, localized text is supplied directly inside the version's content[] array upon creation:
{
"consentType": "TEXT",
"content": [
{
"locale": "en",
"title": "Terms and Conditions",
"content": "Please read and accept our Terms of Service..."
},
{
"locale": "de",
"title": "Allgemeine Geschäftsbedingungen",
"content": "Bitte lesen und akzeptieren Sie unsere AGB..."
}
]
}
1.4 Version Numbering and Retention Management
- Auto-Incremented Versions: Version numbers are sequential integers managed by the server. When calling
POST /consent-srv/consent/versions, do not supply aversionfield. - Immutability: Modifying localized content or configuration creates a new version rather than mutating existing records in place.
- Automated Retention: Each version accepts a
retentionPeriodin months (default:36, maximum:120). Older acceptance audit records exceeding this threshold are cleaned up according to compliance policies.
1.5 Data Subject Rights Catalog (/consent-srv/datasubjectright)
GDPR data subject rights (e.g., right to rectification, right to erasure, right to data portability) are centrally managed. Consent instances link to applicable rights using the allowedDataSubjectRights array.
2. Endpoint Mapping (Legacy vs. v4)
2.1 Administration Endpoints
| Resource | Legacy Endpoint (/consent-management-srv/v2/*) | v4 Endpoint (/consent-srv/*) |
|---|---|---|
| Create Consent Group | POST /consent-management-srv/v2/groups | POST /consent-srv/groups |
| Get Consent Group | GET /consent-management-srv/v2/groups/:consent_group_id | GET /consent-srv/groups/:group_name |
| Update Consent Group | PUT /consent-management-srv/v2/groups/:consent_group_id | PUT /consent-srv/groups/:group_name |
| Delete Consent Group | DELETE /consent-management-srv/v2/groups/:consent_group_id | DELETE /consent-srv/groups/:group_name |
| Search Consent Groups | GET /consent-management-srv/v2/groups | POST /consent-srv/graph/groups |
| Create Consent Instance | POST /consent-management-srv/v2/consent/instance | POST /consent-srv/consents |
| Get Consent Instance | GET /consent-management-srv/v2/consent/instance/:id | GET /consent-srv/consents/:id |
| Update Consent Instance | PUT /consent-management-srv/v2/consent/instance/:id | PUT /consent-srv/consents/:id |
| Delete Consent Instance | DELETE /consent-management-srv/v2/consent/instance/:id | DELETE /consent-srv/consents/:id |
| Create Consent Version | POST /consent-management-srv/v2/consent/versions | POST /consent-srv/consent/versions |
| Get Consent Version | GET /consent-management-srv/v2/consent/versions/:id | GET /consent-srv/consent/versions/:id |
| Search Consent Versions | GET /consent-management-srv/v2/consent/versions | POST /consent-srv/graph/versions |
| Manage Data Subject Rights | (Not available) | `POST |
v4 Consent Group operations use group_name in the path (/consent-srv/groups/:group_name), simplifying tenant-wide configuration compared to legacy technical UUIDs.
2.2 Acceptance and Audit Tracking
| Action | Legacy Endpoint | v4 Endpoint |
|---|---|---|
| Record Acceptance (Authenticated) | POST /consent-management-srv/v2/consent/usage/accept | POST /consent-srv/actions (type: "legalbasistrack") |
| Precheck / Masked Acceptance | POST /consent-management-srv/v2/consent/usage/accept (via q) | POST /consent-management-srv/v2/consent/usage/accept (retained) |
| User Acceptance History | GET /consent-management-srv/v2/consent/usage/users/acceptted/list | GET /consent-srv/users/:sub/actions |
| Search / Filter Audit Logs | POST /consent-management-srv/graph/consents | POST /consent-srv/graph/actions |
2.3 Retained Endpoints
The following legacy endpoints remain active under /consent-management-srv/*:
POST /consent-management-srv/consent/claim/checkPOST /consent-management-srv/consent/claim/acceptPOST /consent-management-srv/consent/claim/revokePOST /consent-management-srv/consent/scope/acceptPOST /consent-management-srv/consent/scope/checkPOST /consent-management-srv/consent/scope/revokePOST /consent-management-srv/v2/consent/usage/accept(retained for unauthenticated query token precheck)
3. Implementation Examples
3.1 Creating a Consent Instance
curl -X POST "https://demo.cidaas.de/consent-srv/consents" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"consent_name": "terms_and_conditions",
"description": "Standard terms and conditions for portal access",
"legalType": "contract",
"interactionMode": "EXPLICIT_ACK_SCREEN",
"showInRegistration": true,
"processingPurposes": ["Account Provisioning", "Service Delivery"],
"involvedParties": ["cidaas Identity Platform"]
}'
3.2 Creating a Localized Version
curl -X POST "https://demo.cidaas.de/consent-srv/consent/versions" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"consent_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"consentType": "TEXT",
"retentionPeriod": 36,
"content": [
{
"locale": "en",
"title": "Terms of Service",
"content": "Please read and accept our terms..."
},
{
"locale": "de",
"title": "Nutzungsbedingungen",
"content": "Bitte lesen und akzeptieren Sie unsere Bedingungen..."
}
]
}'
3.3 Recording User Acceptance
curl -X POST "https://demo.cidaas.de/consent-srv/actions" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"type": "legalbasistrack",
"sub": "45d16e0b-d242-43bb-a570-5b5c777494f1",
"consent_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"consent_version_id": "1fa093ba-f050-4107-8e6f-1f06abac9074",
"status": "ACCEPTED",
"scopes": ["profile", "email"]
}'
4. Error Handling and Remediation
The v4 /consent-srv/* service produces standard customer-actionable errors:
| HTTP Status | Error / Condition | Cause | Client Remediation |
|---|---|---|---|
| 400 Bad Request | InvalidConsentInstance | An unsupported interactionMode was passed for the selected legalType. | Review the Allowed Interaction Modes table and adjust your payload. |
| 400 Bad Request | DuplicateProcessingPurposes | Duplicate entries found in processingPurposes or involvedParties. | Deduplicate the string arrays before sending. |
| 400 Bad Request | RegistrationModeConflict | IMPLICIT_SILENT was passed with showInRegistration: true. | Set an interactive mode (such as EXPLICIT_OPT_IN or ACKNOWLEDGED_ACK_SCREEN). |
| 401 Unauthorized | AccessRightsIssue | Access token missing, expired, or malformed. | Obtain a valid access token from /token-srv/token and pass in Authorization: Bearer <token>. |
| 403 Forbidden | AccessDenied | Caller lacks required scopes (cidaas:consent_write, cidaas:consent_read) or admin roles. | Ensure token includes consent management scopes and admin roles (ADMIN, SECONDARY_ADMIN, or CONSENT_MANAGER). |
| 404 Not Found | DataNotFound | Specified group_name, consent_id, or version ID does not exist. | Confirm resource existence via /consent-srv/graph/groups or /consent-srv/consents/:id. |
| 409 Conflict | EntityAlreadyExists | Consent group name or consent instance name already exists. | Use a unique group_name or consent_name. |
5. Migration Checklist
Follow this checklist to update your integration:
- Audit Active Endpoints: Identify all API calls targeting
/consent-management-srv/v2/*in your backend services, registration pipelines, or custom web portals. - Repoint Base Paths: Update URL routing from
/consent-management-srv/v2/*to/consent-srv/*according to Section 2. - Upgrade Consent Instance Payloads: Ensure all instance creation and update calls include
legalTypeand validinteractionMode. Remove any legacy instance-levelaction_type. - Remove Client-Side Version Integers: Omit the
versionproperty when creating consent versions to allow server-managed auto-increment. - Inline Localized Text: Move localized translations into the version
content[]array; remove legacy calls to/v2/consent/locale. - Migrate Acceptance Recording: Update authenticated tracking calls to
POST /consent-srv/actionswithtype: "legalbasistrack". - Verify Scopes and Permissions: Ensure integration client IDs hold the required
cidaas:consent_read,cidaas:consent_write, andcidaas:consent_deletescopes. - Test End-to-End in Staging: Verify the full lifecycle in your staging environment before deploying to production.
6. Related Resources
- Consent Management OpenAPI Reference
- Consents and Consent Groups Administration Guide
- Consent Configuration Best Practices
Please contact us directly on our support page or reach out to cidaas support at [email protected].