Skip to main content
Version: 4.0.7

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.

Who needs this guide

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​

DimensionLegacy Service (/consent-management-srv/v2/*)v4 Service (/consent-srv/*)
Base Path/consent-management-srv/v2/*/consent-srv/*
Data HierarchyGroup → Instance → Version → Separate LocalesGroup → Instance → Version (with embedded localized content array)
Legal BasisNot explicitly modelledExplicit GDPR Article 6 legalType (consent, contract, legal_obligation, etc.)
UI PresentationInstance action_type (LOGIN/REGISTER)interactionMode enum governing display and consent mechanics
Data Subject RightsNot supported via APIFirst-class catalog under /consent-srv/datasubjectright
Version AssignmentClient-supplied integerServer-assigned, auto-incremented integer
Data RetentionNot configurableConfigurable retentionPeriod per version (default: 36 months, max: 120 months)
Tracking ModelSeparate usage tables and verification endpointsUnified tracking records submitted via POST /consent-srv/actions

1. Core Concept and Schema Changes​

In cidaas v4, every consent instance requires a defined legal basis under GDPR Article 6:

legalType ValueDescriptionGDPR Reference
consentExplicit user consentArticle 6(1)(a)
contractPerformance of a contractArticle 6(1)(b)
legal_obligationCompliance with a legal obligationArticle 6(1)(c)
vital_interestsProtection of vital interestsArticle 6(1)(d)
public_authorityExercise of official authority or public interestArticle 6(1)(e)
legitimate_interestsPursuit of legitimate interestsArticle 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.
legalTypePermitted interactionMode Values
consentAll 6 values (EXPLICIT_OPT_IN, EXPLICIT_ACK_SCREEN, ACKNOWLEDGED_ACK_SCREEN, ACKNOWLEDGED_NOTICE_BANNER, IMPLICIT_NOTICE_BANNER, IMPLICIT_SILENT)
contract, legitimate_interestsAll values except IMPLICIT_NOTICE_BANNER and IMPLICIT_SILENT
legal_obligation, vital_interests, public_authorityACKNOWLEDGED_ACK_SCREEN or ACKNOWLEDGED_NOTICE_BANNER only
Registration Constraint

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 a version field.
  • Immutability: Modifying localized content or configuration creates a new version rather than mutating existing records in place.
  • Automated Retention: Each version accepts a retentionPeriod in months (default: 36, maximum: 120). Older acceptance audit records exceeding this threshold are cleaned up according to compliance policies.

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​

ResourceLegacy Endpoint (/consent-management-srv/v2/*)v4 Endpoint (/consent-srv/*)
Create Consent GroupPOST /consent-management-srv/v2/groupsPOST /consent-srv/groups
Get Consent GroupGET /consent-management-srv/v2/groups/:consent_group_idGET /consent-srv/groups/:group_name
Update Consent GroupPUT /consent-management-srv/v2/groups/:consent_group_idPUT /consent-srv/groups/:group_name
Delete Consent GroupDELETE /consent-management-srv/v2/groups/:consent_group_idDELETE /consent-srv/groups/:group_name
Search Consent GroupsGET /consent-management-srv/v2/groupsPOST /consent-srv/graph/groups
Create Consent InstancePOST /consent-management-srv/v2/consent/instancePOST /consent-srv/consents
Get Consent InstanceGET /consent-management-srv/v2/consent/instance/:idGET /consent-srv/consents/:id
Update Consent InstancePUT /consent-management-srv/v2/consent/instance/:idPUT /consent-srv/consents/:id
Delete Consent InstanceDELETE /consent-management-srv/v2/consent/instance/:idDELETE /consent-srv/consents/:id
Create Consent VersionPOST /consent-management-srv/v2/consent/versionsPOST /consent-srv/consent/versions
Get Consent VersionGET /consent-management-srv/v2/consent/versions/:idGET /consent-srv/consent/versions/:id
Search Consent VersionsGET /consent-management-srv/v2/consent/versionsPOST /consent-srv/graph/versions
Manage Data Subject Rights(Not available)`POST
Groups Addressed by Name

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​

ActionLegacy Endpointv4 Endpoint
Record Acceptance (Authenticated)POST /consent-management-srv/v2/consent/usage/acceptPOST /consent-srv/actions (type: "legalbasistrack")
Precheck / Masked AcceptancePOST /consent-management-srv/v2/consent/usage/accept (via q)POST /consent-management-srv/v2/consent/usage/accept (retained)
User Acceptance HistoryGET /consent-management-srv/v2/consent/usage/users/acceptted/listGET /consent-srv/users/:sub/actions
Search / Filter Audit LogsPOST /consent-management-srv/graph/consentsPOST /consent-srv/graph/actions

2.3 Retained Endpoints​

The following legacy endpoints remain active under /consent-management-srv/*:

  • POST /consent-management-srv/consent/claim/check
  • POST /consent-management-srv/consent/claim/accept
  • POST /consent-management-srv/consent/claim/revoke
  • POST /consent-management-srv/consent/scope/accept
  • POST /consent-management-srv/consent/scope/check
  • POST /consent-management-srv/consent/scope/revoke
  • POST /consent-management-srv/v2/consent/usage/accept (retained for unauthenticated query token precheck)

3. Implementation Examples​

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 StatusError / ConditionCauseClient Remediation
400 Bad RequestInvalidConsentInstanceAn unsupported interactionMode was passed for the selected legalType.Review the Allowed Interaction Modes table and adjust your payload.
400 Bad RequestDuplicateProcessingPurposesDuplicate entries found in processingPurposes or involvedParties.Deduplicate the string arrays before sending.
400 Bad RequestRegistrationModeConflictIMPLICIT_SILENT was passed with showInRegistration: true.Set an interactive mode (such as EXPLICIT_OPT_IN or ACKNOWLEDGED_ACK_SCREEN).
401 UnauthorizedAccessRightsIssueAccess token missing, expired, or malformed.Obtain a valid access token from /token-srv/token and pass in Authorization: Bearer <token>.
403 ForbiddenAccessDeniedCaller 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 FoundDataNotFoundSpecified group_name, consent_id, or version ID does not exist.Confirm resource existence via /consent-srv/graph/groups or /consent-srv/consents/:id.
409 ConflictEntityAlreadyExistsConsent 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:

  1. Audit Active Endpoints: Identify all API calls targeting /consent-management-srv/v2/* in your backend services, registration pipelines, or custom web portals.
  2. Repoint Base Paths: Update URL routing from /consent-management-srv/v2/* to /consent-srv/* according to Section 2.
  3. Upgrade Consent Instance Payloads: Ensure all instance creation and update calls include legalType and valid interactionMode. Remove any legacy instance-level action_type.
  4. Remove Client-Side Version Integers: Omit the version property when creating consent versions to allow server-managed auto-increment.
  5. Inline Localized Text: Move localized translations into the version content[] array; remove legacy calls to /v2/consent/locale.
  6. Migrate Acceptance Recording: Update authenticated tracking calls to POST /consent-srv/actions with type: "legalbasistrack".
  7. Verify Scopes and Permissions: Ensure integration client IDs hold the required cidaas:consent_read, cidaas:consent_write, and cidaas:consent_delete scopes.
  8. Test End-to-End in Staging: Verify the full lifecycle in your staging environment before deploying to production.

info
Need Support?

Please contact us directly on our support page or reach out to cidaas support at [email protected].