> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consent Management Overview

> Understand the Baanx consent management system, policy types, and workflow for regulatory compliance

## What is Consent Management?

The Baanx Consent Management API (V2) provides a comprehensive system for collecting, tracking, and managing user consent throughout the user lifecycle. It enables compliant data collection with complete audit trails for regulatory requirements like GDPR, CCPA, and industry-specific regulations.

<Note>
  All consent operations maintain an **immutable audit trail** for compliance reporting and regulatory audits.
</Note>

## Why Use Consent Management?

<CardGroup cols={2}>
  <Card title="Regulatory Compliance" icon="scale-balanced">
    Meet GDPR, CCPA, and other data privacy regulations with complete audit trails
  </Card>

  <Card title="User Trust" icon="shield-check">
    Transparent consent collection builds trust with clear opt-in/opt-out mechanisms
  </Card>

  <Card title="Flexible Policies" icon="globe">
    Region-specific policy types (US vs Global) with different consent requirements
  </Card>

  <Card title="Audit Trail" icon="clock-rotate-left">
    Complete change history with timestamps, IP addresses, and user agent tracking
  </Card>
</CardGroup>

## Consent Types

The API supports five distinct consent types:

| Consent Type             | Description                                            | Required In    |
| ------------------------ | ------------------------------------------------------ | -------------- |
| `eSignAct`               | Electronic signature agreement (E-Sign Act compliance) | US policy only |
| `termsAndPrivacy`        | Terms of service and privacy policy acceptance         | All policies   |
| `marketingNotifications` | Marketing communications opt-in                        | All policies   |
| `smsNotifications`       | SMS/text message notifications                         | All policies   |
| `emailNotifications`     | Email notifications                                    | All policies   |

<Warning>
  **Policy-Specific Requirements**: US policy requires all 5 consent types (includes `eSignAct` for E-Sign Act compliance). Global policy requires 4 consent types (excludes `eSignAct`).
</Warning>

## Policy Types

### US Policy

Used for US-based users and deployments within the United States.

**Required Consents:**

* ✅ `eSignAct` (E-Sign Act compliance)
* ✅ `termsAndPrivacy`
* ✅ `marketingNotifications`
* ✅ `smsNotifications`
* ✅ `emailNotifications`

<Info>
  The US policy requires `eSignAct` consent for compliance with the federal Electronic Signatures in Global and National Commerce Act (E-Sign Act).
</Info>

### Global Policy

Used for international users and deployments outside the US.

**Required Consents:**

* ✅ `termsAndPrivacy`
* ✅ `marketingNotifications`
* ✅ `smsNotifications`
* ✅ `emailNotifications`

<Note>
  The Global policy does not require `eSignAct` consent as this is a US-specific regulatory requirement.
</Note>

## Consent Status Values

Each consent can have one of three status values:

| Status    | Description                                   | Use Case                                         |
| --------- | --------------------------------------------- | ------------------------------------------------ |
| `granted` | User has provided consent                     | Initial opt-in, re-consent after revocation      |
| `denied`  | User has explicitly refused consent           | Opt-out during onboarding                        |
| `revoked` | Previously granted consent has been withdrawn | User-initiated revocation, right to be forgotten |

## Workflow Overview

The consent management workflow follows a structured lifecycle:

```mermaid theme={null}
sequenceDiagram
    participant Client as Your Application
    participant API as Baanx API
    participant User as End User

    Note over Client,API: 1. Onboarding Phase
    Client->>API: POST /v2/consent/onboarding
    Note right of API: Create consent set with<br/>temporary onboardingId
    API-->>Client: consentSetId

    Note over Client,User: 2. User Registration
    Client->>User: Complete registration
    User-->>Client: userId created

    Note over Client,API: 3. Linking Phase
    Client->>API: PATCH /v2/consent/onboarding/{consentSetId}
    Note right of API: Link userId to<br/>consent set
    API-->>Client: Linked consent set

    Note over Client,API: 4. Status & Audit
    Client->>API: GET /v2/consent/user/{userId}
    API-->>Client: Consent status (complete/incomplete)

    Client->>API: GET /v2/consent/user/{userId}/audit
    API-->>Client: Complete audit trail

    Note over Client,API: 5. Revocation (Optional)
    Client->>API: DELETE /v2/consent/consentSet/{id}/consent/{id}
    Note right of API: Revoke specific consent<br/>maintaining audit
    API-->>Client: Revocation recorded
```

### Workflow Stages

<Steps>
  <Step title="Create Onboarding Consent">
    Collect consent during user registration using a temporary `onboardingId` before a permanent `userId` exists.

    **When:** Registration forms, KYC processes, mobile app onboarding
  </Step>

  <Step title="Link User to Consent Set">
    Associate the permanent `userId` with the consent set after account creation completes.

    **When:** Post-registration linking, account activation, email verification completion
  </Step>

  <Step title="Retrieve Consent Status">
    Check aggregated consent status for a user with short summary or full details.

    **When:** Login checks, feature access validation, compliance reporting
  </Step>

  <Step title="Track Changes with Audit Trail">
    Access paginated audit log of all consent changes with complete history.

    **When:** Compliance audits, regulatory reporting, user consent history review
  </Step>

  <Step title="Revoke Consent (Optional)">
    Allow users to withdraw specific consents while maintaining immutable audit trail.

    **When:** User settings, privacy preferences, right to be forgotten requests
  </Step>
</Steps>

## HATEOAS Navigation

All API responses include a `_links` section for dynamic API discovery:

```json theme={null}
{
  "_links": {
    "self": {
      "href": "https://api.baanx.com/v2/consent/user/user_123",
      "method": "GET"
    },
    "audit": {
      "href": "https://api.baanx.com/v2/consent/user/user_123/audit",
      "method": "GET"
    },
    "full": {
      "href": "https://api.baanx.com/v2/consent/user/user_123?full=true",
      "method": "GET"
    }
  }
}
```

This enables dynamic navigation without hardcoded URLs in your application.

## Key Features

### Immutable Audit Trail

Every consent change is recorded with:

* **Timestamp**: ISO 8601 date-time
* **IP Address**: User's IP at time of consent
* **User Agent**: Browser/device information
* **Before/After Snapshots**: Complete state changes

### Metadata Support

Enhance consent records with custom metadata:

```json theme={null}
{
  "metadata": {
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)",
    "timestamp": "2024-01-15T10:30:00Z",
    "clientId": "mobile-app-ios-v2.1.0",
    "version": "v2.0.0"
  }
}
```

### Flexible Retrieval

Choose between response modes based on your needs:

* **Short Mode**: Status only (`complete`, `incomplete`, `none`)
* **Full Mode**: All consent sets with detailed records

## Next Steps

<CardGroup cols={2}>
  <Card title="Implementation Guide" icon="code" href="/guides/consent/implementation">
    Step-by-step integration with code examples
  </Card>

  <Card title="Compliance & Best Practices" icon="clipboard-check" href="/guides/consent/compliance">
    Regulatory requirements and audit strategies
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/consent/create-onboarding-consent">
    Detailed endpoint documentation
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/consent/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>