{ "openapi": "3.0.3", "info": { "version": "1.0.0", "title": "Axeptio Headless CMP API", "description": "Comprehensive Consent Management Platform API for headless implementations.\n\n## API Overview\n\nThis API provides complete CMP functionality including:\n- **Authentication & Authorization**: Secure access control and user management\n- **Project Management**: Create and configure consent collection projects\n- **Consent Management**: Collect, store, and retrieve user consent decisions\n- **Cookie & Vendor Configuration**: Define consent categories and third-party services\n- **Analytics & Reporting**: Access consent statistics and compliance reports\n- **Organization Management**: Multi-tenant support for agencies and enterprises\n\n## Authentication\n\nAll endpoints require Bearer token authentication:\n```\nAuthorization: Bearer YOUR_API_TOKEN\n```\n\n## Rate Limits\n\nRate limits vary by customer tier:\n- **Free**: 100 requests per minute\n- **Pro**: 1000 requests per minute\n- **Enterprise**: 10000 requests per minute\n\n## Platform Support\n\nThis API supports all platforms and frameworks including web, mobile (iOS, Android, React Native, Flutter), and server-side implementations." }, "tags": [ { "name": "Consent Ingestion", "description": "High-performance consent collection endpoints optimized with offline sync capabilities and batch operations.", "externalDocs": { "description": "Mobile Consent Collection Guide", "url": "https://docs.axeptio.tech/mobile/consent-collection" } }, { "name": "Consent Reading", "description": "consent retrieval with compact response formats and platform-specific optimizations for fast mobile loading.", "externalDocs": { "description": "Mobile Consent Reading Guide", "url": "https://docs.axeptio.tech/mobile/consent-reading" } }, { "name": "Batch Operations", "description": "Bulk consent operations designed for mobile offline sync scenarios, allowing submission of multiple consent records in a single request.", "externalDocs": { "description": "Mobile Offline Sync Guide", "url": "https://docs.axeptio.tech/mobile/offline-sync" } }, { "name": "Health Check", "description": "service health monitoring with circuit breaker status and disaster recovery information for application reliability.", "externalDocs": { "description": "Mobile Monitoring Guide", "url": "https://docs.axeptio.tech/mobile/monitoring" } }, { "name": "CORS", "description": "Cross-Origin Resource Sharing support for mobile web views, hybrid apps, and browser-based mobile implementations.", "externalDocs": { "description": "Mobile CORS Setup", "url": "https://docs.axeptio.tech/mobile/cors" } }, { "name": "SDK", "description": "endpoints designed for native iOS, Android, React Native, and Flutter applications", "externalDocs": { "description": "Mobile Integration Guide", "url": "https://axeptio.tech/mobile-integration" } } ], "paths": { "/mobile/consents/{clientId}/{collection}/{configId}": { "post": { "tags": [ "Consent Ingestion" ], "summary": "Submit consent record for mobile applications", "description": "Records user consent preferences with mobile-specific optimizations including offline sync support and platform-specific metadata", "operationId": "mobile_submitMobileConsent", "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Project/Client identifier (24-character hex string)", "schema": { "type": "string", "pattern": "^[a-f\\d]{24}$", "example": "507f1f77bcf86cd799439011" } }, { "name": "collection", "in": "path", "required": true, "description": "Type of consent being collected", "schema": { "type": "string", "enum": [ "processings", "contracts", "contractsV2", "cookies" ], "example": "processings" } }, { "name": "configId", "in": "path", "required": true, "description": "Configuration identifier, can include consentFor suffix for contractsV2", "schema": { "type": "string", "maxLength": 255, "example": "507f1f77bcf86cd799439012" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentSubmissionRequest" }, "examples": { "ios-consent": { "summary": "iOS app consent submission", "value": { "accept": true, "token": "mobile_user_12345", "timestamp": "2025-09-03T10:30:00Z", "headers": { "x-mobile-platform": "ios", "x-mobile-version": "17.0", "x-app-version": "2.1.0", "x-device-id": "uuid-device-123", "user-agent": "MyApp/2.1.0 (iOS 17.0; iPhone)" }, "preferences": { "vendors": { "google": true, "facebook": false, "analytics": true }, "config": { "name": "Cookie Consent", "language": "en", "consentMode": "opt-in", "mobileContext": { "platform": "ios", "offline": false, "networkType": "wifi" } }, "googleConsentMode": { "version": 2, "analytics_storage": "granted", "ad_storage": "denied" } } } }, "android-batch": { "summary": "Android offline sync batch", "value": { "accept": false, "token": "android_user_67890", "timestamp": "2025-09-03T09:15:00Z", "headers": { "x-mobile-platform": "android", "x-mobile-version": "14", "x-app-version": "3.2.1", "x-device-id": "android-uuid-456", "x-session-id": "session-789" }, "preferences": { "config": { "mobileContext": { "platform": "android", "offline": true, "syncBatch": "batch-002", "networkType": "cellular" } } } } }, "react-native": { "summary": "React Native cross-platform consent", "value": { "accept": true, "token": "rn_user_11111", "headers": { "x-mobile-platform": "react-native", "x-app-version": "1.5.2" }, "preferences": { "vendors": { "amplitude": true, "mixpanel": true }, "config": { "mobileContext": { "platform": "react-native", "offline": false } } } } } } } } }, "responses": { "200": { "description": "Consent successfully recorded", "headers": { "X-DB-Mode": { "description": "Database mode used (normal/pool)", "schema": { "type": "string" } }, "X-Circuit-Breaker": { "description": "Circuit breaker status", "schema": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "X-S3-Fallback": { "description": "S3 fallback status", "schema": { "type": "string", "enum": [ "enabled", "disabled" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentSubmissionResponse" } } } }, "400": { "description": "Invalid request data or validation error", "content": { "text/plain": { "examples": { "validation-error": { "summary": "Validation error", "value": "Validation error: /accept must be boolean [requestId: abc123]" }, "parse-error": { "summary": "Parameter parsing error", "value": "Error while parsing path parameters [requestId: def456]" } } } } }, "500": { "description": "Internal server error", "content": { "text/plain": { "examples": { "db-error": { "summary": "Database error", "value": "Error while inserting consent in DB [requestId: ghi789]" }, "stream-error": { "summary": "Kinesis stream error", "value": "Error while sending consent to stream [requestId: jkl012]" }, "fallback-error": { "summary": "Both DB and S3 fallback failed", "value": "Error while inserting consent in DB and S3 fallback [requestId: mno345]" } } } } } } }, "options": { "tags": [ "CORS" ], "summary": "CORS preflight for consent ingestion", "description": "Handles CORS preflight requests for mobile consent submission", "responses": { "200": { "description": "CORS preflight response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } }, "Access-Control-Allow-Methods": { "schema": { "type": "string" } }, "Access-Control-Allow-Headers": { "schema": { "type": "string" } } } } } } }, "/mobile/health": { "get": { "tags": [ "Health Check" ], "summary": "Mobile service health check", "description": "Health check endpoint optimized for mobile monitoring and circuit breaker status", "responses": { "200": { "description": "Service healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheckResponse" } } } } } } }, "/mobile/configurations/{projectId}": { "get": { "tags": [ "Mobile SDK" ], "summary": "Get mobile-optimized project configuration", "description": "Retrieve project configuration optimized for mobile apps with minimal payload size and mobile-specific settings.", "operationId": "mobile_getMobileConfig", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project identifier", "example": "60f7b3b3d1b6c4a7c8e9f0a1" }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ios", "android", "react-native", "flutter" ] }, "description": "Mobile platform for optimized responses", "example": "ios" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string" }, "description": "App version for feature flag support", "example": "1.2.3" } ], "responses": { "200": { "description": "Mobile project configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileProjectConfig" }, "examples": { "ios-config": { "summary": "iOS project configuration", "value": { "projectId": "60f7b3b3d1b6c4a7c8e9f0a1", "name": "My Mobile App", "platform": "ios", "consentCategories": [ { "id": "analytics", "name": "Analytics", "description": "Help us improve the app", "required": false, "vendors": [ "google_analytics", "mixpanel" ] } ], "settings": { "theme": "light", "animationStyle": "fade", "position": "bottom" }, "legal": { "privacyPolicyUrl": "https://app.com/privacy", "termsUrl": "https://app.com/terms" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/mobile/token": { "get": { "tags": [ "Mobile SDK" ], "summary": "Generate consent token", "description": "Generate a cryptographically secure random token for consent identification. This token is used to identify and link consent choices in the consent management system.", "operationId": "mobile_generateConsentToken", "responses": { "200": { "description": "Successfully generated consent token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentTokenResponse" }, "examples": { "token-response": { "summary": "Generated consent token", "value": { "token": "abc123def456ghi789" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "405": { "description": "Method not allowed - Only GET requests supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/mobile/auth/me": { "get": { "tags": [ "Mobile SDK" ], "summary": "Validate bearer token and get project information", "description": "Validates the provided bearer token and returns associated project information and tier details.", "operationId": "mobile_validateBearerToken", "responses": { "200": { "description": "Token validation successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthValidationResponse" }, "examples": { "valid-token": { "summary": "Valid token response", "value": { "valid": true, "projectId": "67fcdb2b52ab9a99a5865f4d", "tier": "enterprise" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" }, "examples": { "invalid-token": { "summary": "Invalid token", "value": { "error": "unauthorized", "message": "Invalid or missing authorization header" } } } } } }, "405": { "description": "Method not allowed - Only GET requests supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/mobile/vendors/{projectId}": { "get": { "tags": [ "Mobile SDK" ], "summary": "Get project vendors", "description": "Retrieve all vendors for a project with mobile-optimized data including imgix-optimized images for different screen densities.", "operationId": "mobile_getProjectVendors", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project identifier", "example": "67fcdb2b52ab9a99a5865f4d" } ], "responses": { "200": { "description": "Successfully retrieved project vendors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorsResponse" }, "examples": { "vendors-response": { "summary": "Project vendors with optimization", "value": { "projectId": "67fcdb2b52ab9a99a5865f4d", "vendors": [ { "id": "62fd02d250c4539d3456e350", "name": "googletagmanager", "title": "Google Tag Manager", "description": "Système de gestion de balisage", "longDescription": "Mise en place d'un système de balisage pour traiter plus facilement les informations liées aux données.", "category": "Fonctionnels, Gestion des étiquettes", "categories": [ "Fonctionnels", "Gestion des étiquettes" ], "type": "functional, tag_management", "domain": "https://tagmanager.google.com/", "policyUrl": "https://marketingplatform.google.com/about/analytics/tag-manager/use-policy/", "isAxeptioVendor": true, "image": { "identifier": "googletagmanager", "baseUrl": "https://axeptio.imgix.net/vendors/googletagmanager", "optimized": { "small": "https://axeptio.imgix.net/vendors/googletagmanager?w=32&h=32&fit=crop&auto=format,compress", "medium": "https://axeptio.imgix.net/vendors/googletagmanager?w=64&h=64&fit=crop&auto=format,compress", "large": "https://axeptio.imgix.net/vendors/googletagmanager?w=128&h=128&fit=crop&auto=format,compress" }, "fallbackUrl": "https://favicons.axept.io/favicons?domain=tagmanager.google.com" } } ], "totalVendors": 5, "categories": [ "Fonctionnels", "Gestion des étiquettes", "Réseaux sociaux" ], "fetchedAt": "2025-09-12T14:30:00.000Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/mobile/vendors/{projectId}/categories": { "get": { "tags": [ "Mobile SDK" ], "summary": "Get vendors by category", "description": "Retrieve vendors organized by category for a project, useful for grouped vendor displays in mobile UIs.", "operationId": "mobile_getVendorCategories", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project identifier", "example": "67fcdb2b52ab9a99a5865f4d" } ], "responses": { "200": { "description": "Successfully retrieved vendor categories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorCategoriesResponse" }, "examples": { "categories-response": { "summary": "Vendors grouped by category", "value": { "projectId": "67fcdb2b52ab9a99a5865f4d", "categories": [ { "name": "Fonctionnels", "vendors": [ { "id": "62fd02d250c4539d3456e350", "name": "googletagmanager", "title": "Google Tag Manager" } ], "count": 3 }, { "name": "Réseaux sociaux", "vendors": [ { "id": "6282644788ca8e0d930c0082", "name": "twitter", "title": "X" } ], "count": 2 } ], "totalCategories": 4, "totalVendors": 12, "fetchedAt": "2025-09-12T14:30:00.000Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/mobile/vendors/{projectId}/{configId}": { "get": { "tags": [ "Mobile SDK" ], "summary": "Get vendors for specific configuration", "description": "Retrieve vendors for a specific project configuration. This provides more precise vendor lists for context-specific consent collection compared to the aggregated project vendors endpoint.", "operationId": "mobile_getConfigurationVendors", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Project identifier (MongoDB ObjectId)", "example": "67fcdb2b52ab9a99a5865f4d" }, { "name": "configId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "description": "Configuration identifier (MongoDB ObjectId)", "example": "67fcddc2673e895f81feb6c3" } ], "responses": { "200": { "description": "Successfully retrieved configuration vendors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationVendorsResponse" }, "examples": { "config-vendors-response": { "summary": "Configuration-specific vendors", "value": { "projectId": "67fcdb2b52ab9a99a5865f4d", "configId": "67fcddc2673e895f81feb6c3", "configName": "fr-eu-14-04-2025", "vendors": [ { "id": "62fd02d250c4539d3456e350", "name": "googletagmanager", "title": "Google Tag Manager", "description": "Système de gestion de balisage", "longDescription": "Google Tag Manager facilite la mise à jour des balises de mesure d'audience et de remarketing sur vos sites Web et vos applications mobiles.", "category": "Fonctionnels", "categories": [ "Fonctionnels" ], "type": "cookie", "domain": "https://tagmanager.google.com/", "policyUrl": "https://marketingplatform.google.com/about/analytics/tag-manager/use-policy/", "isAxeptioVendor": true, "image": { "identifier": "googletagmanager", "baseUrl": "https://axeptio.imgix.net/vendors/googletagmanager", "optimized": { "small": "https://axeptio.imgix.net/vendors/googletagmanager?w=32&h=32&fit=crop&auto=format,compress", "medium": "https://axeptio.imgix.net/vendors/googletagmanager?w=64&h=64&fit=crop&auto=format,compress", "large": "https://axeptio.imgix.net/vendors/googletagmanager?w=128&h=128&fit=crop&auto=format,compress" }, "fallbackUrl": "https://favicons.axept.io/favicons?domain=tagmanager.google.com" } } ], "totalVendors": 1, "categories": [ "Fonctionnels" ], "fetchedAt": "2025-09-22T10:30:00.000Z" } } } } } }, "400": { "description": "Invalid project ID or configuration ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "403": { "description": "Access denied to this project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "404": { "description": "Project or configuration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/mobile/analytics/evts": { "post": { "tags": [ "Mobile SDK" ], "summary": "Submit analytics events", "description": "Submit analytics and behavioral events from mobile applications. Supports both single events and batch submissions for offline sync scenarios.", "operationId": "mobile_submitMobileEvents", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MobileEvent" }, { "type": "array", "items": { "$ref": "#/components/schemas/MobileEvent" } } ] }, "examples": { "single-event": { "summary": "Single event submission", "value": { "type": "consent_displayed", "timestamp": "2025-09-18T10:30:00.000Z", "metadata": { "source": "sdk-app", "platform": "ios", "appVersion": "1.2.3" }, "projectId": "67fcdb2b52ab9a99a5865f4d", "correlationId": "consent-flow-abc123" } }, "batch-events": { "summary": "Batch event submission for offline sync", "value": [ { "type": "consent_displayed", "timestamp": "2025-09-18T10:30:00.000Z", "metadata": { "source": "sdk-app", "platform": "ios" }, "projectId": "67fcdb2b52ab9a99a5865f4d" }, { "type": "consent_accepted", "timestamp": "2025-09-18T10:30:15.000Z", "metadata": { "source": "sdk-app", "platform": "ios", "categories": [ "analytics", "marketing" ] }, "projectId": "67fcdb2b52ab9a99a5865f4d" } ] } } } } }, "responses": { "200": { "description": "Events successfully processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventSubmissionResponse" }, "examples": { "success-response": { "summary": "Successful event submission", "value": { "success": true, "processed": 2, "timestamp": "2025-09-18T10:30:16.000Z", "batchId": "batch-abc123-def456" } } } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" }, "examples": { "invalid-payload": { "summary": "Invalid event structure", "value": { "error": "invalid_payload", "message": "Missing required field 'type' in event object" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" }, "examples": { "rate-limit": { "summary": "Rate limit exceeded", "value": { "error": "rate_limit_exceeded", "message": "Request rate limit limit exceeded. Please wait before sending more events." } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/mobile/client/{projectId}/consents/{token}": { "get": { "tags": [ "Consent Reading" ], "summary": "Retrieve single consent record by token", "description": "Retrieve a specific consent record using a consent token. This is the primary endpoint used by mobile applications and widgets to fetch individual consent records.", "operationId": "getSingleConsent", "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Project identifier", "schema": { "type": "string", "pattern": "^[a-f\\d]{24}$" } }, { "name": "token", "in": "path", "required": true, "description": "Consent token", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Consent record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentReadResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "text/plain": { "examples": { "invalid-params": { "value": "Error while getting params [requestId: abc123]" } } } } }, "404": { "description": "Consent not found", "content": { "text/plain": { "examples": { "not-found": { "value": "Consent not found [requestId: abc123]" } } } } }, "500": { "description": "Database error", "content": { "text/plain": { "examples": { "db-error": { "value": "Error while reading consent in DB [requestId: def456]" } } } } } } }, "options": { "tags": [ "CORS" ], "summary": "CORS preflight for single consent reading", "responses": { "200": { "description": "CORS preflight response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } }, "Access-Control-Allow-Methods": { "schema": { "type": "string" } }, "Access-Control-Allow-Headers": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "ConsentSubmissionRequest": { "type": "object", "required": [ "accept", "token", "preferences" ], "properties": { "_id": { "oneOf": [ { "type": "string", "pattern": "^[a-f\\d]{24}$", "description": "MongoDB ObjectId" }, { "type": "string", "format": "uuid", "description": "UUID v7 for improved sorting and indexing" } ], "description": "Unique identifier for the consent record" }, "accept": { "type": "boolean", "description": "Whether the user accepted or denied consent" }, "token": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User token for consent tracking" }, "value": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Optional consent value" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO timestamp when consent was given (defaults to server time)" }, "headers": { "type": "object", "description": "Mobile-specific request headers and metadata", "properties": { "user-agent": { "type": "string" }, "x-mobile-platform": { "type": "string", "enum": [ "ios", "android", "react-native", "flutter", "xamarin", "cordova" ] }, "x-mobile-version": { "type": "string" }, "x-app-version": { "type": "string" }, "x-device-id": { "type": "string" }, "x-session-id": { "type": "string" } } }, "preferences": { "type": "object", "description": "Detailed consent preferences and mobile-specific data", "properties": { "vendors": { "type": "object", "description": "Vendor-specific consent preferences", "additionalProperties": { "type": "boolean" } }, "config": { "type": "object", "properties": { "name": { "type": "string" }, "identifier": { "type": "string" }, "language": { "type": "string" }, "consentMode": { "type": "string" }, "displayMode": { "type": "string" }, "tag": { "type": "string" }, "mobileContext": { "type": "object", "properties": { "platform": { "type": "string" }, "offline": { "type": "boolean" }, "syncBatch": { "type": "string" }, "networkType": { "type": "string", "enum": [ "wifi", "cellular", "unknown" ] } } } } }, "googleConsentMode": { "type": "object", "properties": { "version": { "type": "number" }, "analytics_storage": { "type": "string", "enum": [ "granted", "denied" ] }, "ad_storage": { "type": "string", "enum": [ "granted", "denied" ] }, "ad_user_data": { "type": "string", "enum": [ "granted", "denied" ] }, "ad_personalization": { "type": "string", "enum": [ "granted", "denied" ] }, "functionality_storage": { "type": "string", "enum": [ "granted", "denied" ] }, "personalization_storage": { "type": "string", "enum": [ "granted", "denied" ] }, "security_storage": { "type": "string", "enum": [ "granted", "denied" ] } } }, "consentFor": { "type": "string" }, "version": { "type": "number" } }, "additionalProperties": true } } }, "ConsentSubmissionResponse": { "type": "object", "properties": { "consentId": { "type": "string", "description": "Generated consent UUID" }, "_id": { "type": "string" }, "projectId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "accept": { "type": "boolean" }, "collection": { "type": "string" }, "identifier": { "type": "string" }, "token": { "type": "string" }, "value": { "type": "string" }, "preferences": { "type": "object" } } }, "ConsentBatchRequest": { "type": "object", "required": [ "consents" ], "properties": { "batchId": { "type": "string", "description": "Unique identifier for this batch" }, "syncContext": { "type": "object", "properties": { "platform": { "type": "string" }, "appVersion": { "type": "string" }, "offlineDuration": { "type": "number" }, "networkQuality": { "type": "string" } } }, "consents": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "clientId", "collection", "configId", "consent" ], "properties": { "clientId": { "type": "string", "pattern": "^[a-f\\d]{24}$" }, "collection": { "type": "string", "enum": [ "processings", "contracts", "contractsV2", "cookies" ] }, "configId": { "type": "string" }, "consent": { "$ref": "#/components/schemas/ConsentSubmissionRequest" } } } } } }, "ConsentBatchResponse": { "type": "object", "properties": { "batchId": { "type": "string" }, "processed": { "type": "number" }, "succeeded": { "type": "number" }, "failed": { "type": "number" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "status": { "type": "string", "enum": [ "success", "error" ] }, "consentId": { "type": "string" }, "error": { "type": "string" } } } } } }, "ConsentReadResponse": { "oneOf": [ { "type": "object", "properties": { "accept": { "type": "boolean", "const": false } }, "description": "No consent found" }, { "type": "object", "properties": { "_id": { "type": "string" }, "projectId": { "type": "string" }, "token": { "type": "string" }, "collection": { "type": "string" }, "identifier": { "type": "string" }, "accept": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "headers": { "type": "object" }, "value": { "type": "string" }, "preferences": { "type": "object", "properties": { "vendors": { "type": "object" }, "config": { "type": "object" }, "googleConsentMode": { "type": "object" }, "mobileOptimized": { "type": "object", "properties": { "compactVendors": { "type": "array" }, "essentialOnly": { "type": "boolean" } } } } } } } ] }, "HealthCheckResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded" ] }, "timestamp": { "type": "string", "format": "date-time" }, "services": { "type": "object", "properties": { "database": { "type": "string", "enum": [ "up", "down", "fallback" ] }, "kinesis": { "type": "string", "enum": [ "up", "down" ] }, "s3_fallback": { "type": "string", "enum": [ "available", "unavailable" ] } } }, "circuit_breaker": { "type": "boolean" }, "disaster_recovery": { "type": "boolean" } } }, "ConfigurationDiscoveryResponse": { "type": "object", "required": [ "projectId", "configurations" ], "properties": { "projectId": { "type": "string", "description": "Project identifier" }, "configurations": { "type": "array", "description": "Available consent configurations", "items": { "$ref": "#/components/schemas/ConfigurationSummary" } }, "defaultConfigId": { "type": "string", "description": "Default configuration identifier to use" } } }, "ConfigurationSummary": { "type": "object", "required": [ "identifier", "name" ], "properties": { "identifier": { "type": "string", "description": "Configuration identifier (MongoDB ObjectId)" }, "name": { "type": "string", "description": "Configuration name" }, "language": { "type": "string", "description": "Configuration language code (e.g., 'en', 'fr')" }, "country": { "type": "string", "description": "Country or region code (e.g., 'EU', 'US')" }, "title": { "type": "string", "description": "Display title for the configuration" }, "isDefault": { "type": "boolean", "description": "Whether this is the default configuration" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error message" } } }, "MobileProjectConfig": { "type": "object", "properties": { "projectId": { "type": "string", "description": "Unique project identifier" }, "name": { "type": "string", "description": "Project display name" }, "platform": { "type": "string", "enum": [ "ios", "android", "react-native", "flutter" ], "description": "Target mobile platform" }, "consentCategories": { "type": "array", "items": { "$ref": "#/components/schemas/MobileConsentCategory" } }, "settings": { "$ref": "#/components/schemas/MobileUISettings" }, "legal": { "$ref": "#/components/schemas/LegalUrls" } } }, "MobileConsentCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Category identifier" }, "name": { "type": "string", "description": "Display name for the category" }, "description": { "type": "string", "description": "User-friendly description" }, "required": { "type": "boolean", "description": "Whether this category is mandatory" }, "vendors": { "type": "array", "items": { "type": "string" }, "description": "Associated vendor identifiers" } } }, "MobileUISettings": { "type": "object", "properties": { "theme": { "type": "string", "enum": [ "light", "dark", "auto" ], "description": "UI theme preference" }, "animationStyle": { "type": "string", "enum": [ "fade", "slide", "none" ], "description": "Animation style for consent UI" }, "position": { "type": "string", "enum": [ "top", "bottom", "center" ], "description": "Preferred UI position" } } }, "LegalUrls": { "type": "object", "properties": { "privacyPolicyUrl": { "type": "string", "format": "uri", "description": "Privacy policy URL" }, "termsUrl": { "type": "string", "format": "uri", "description": "Terms of service URL" } } }, "ConsentBatchRequest1": { "type": "object", "properties": { "projectId": { "type": "string", "description": "Project identifier" }, "consents": { "type": "array", "items": { "$ref": "#/components/schemas/MobileConsentRecord" }, "description": "Array of consent records to submit" } } }, "MobileConsentRecord": { "type": "object", "properties": { "userToken": { "type": "string", "description": "Unique user identifier" }, "timestamp": { "type": "string", "format": "date-time", "description": "Consent collection timestamp" }, "preferences": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "User consent preferences by category" }, "metadata": { "$ref": "#/components/schemas/MobileMetadata" } } }, "MobileMetadata": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "ios", "android", "react-native", "flutter" ], "description": "Mobile platform" }, "appVersion": { "type": "string", "description": "Application version" }, "sdkVersion": { "type": "string", "description": "SDK version used" }, "deviceId": { "type": "string", "description": "Anonymous device identifier" }, "locale": { "type": "string", "description": "User locale (e.g., en-US)" } } }, "ConsentBatchResponse1": { "type": "object", "properties": { "processed": { "type": "integer", "description": "Number of successfully processed records" }, "failed": { "type": "integer", "description": "Number of failed records" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchResult" } } } }, "BatchResult": { "type": "object", "properties": { "userToken": { "type": "string", "description": "User token from request" }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Processing status" }, "error": { "type": "string", "description": "Error message if status is error" } } }, "MobileConsentState": { "type": "object", "properties": { "userToken": { "type": "string", "description": "User identifier" }, "projectId": { "type": "string", "description": "Project identifier" }, "preferences": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Current consent preferences" }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "version": { "type": "integer", "description": "Consent record version" } } }, "ConsentTokenResponse": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "Cryptographically secure random consent token", "example": "abc123def456ghi789" } } }, "AuthValidationResponse": { "type": "object", "required": [ "valid" ], "properties": { "valid": { "type": "boolean", "description": "Whether the bearer token is valid", "example": true }, "projectId": { "type": "string", "description": "Project ID associated with the token (if valid)", "example": "67fcdb2b52ab9a99a5865f4d" }, "tier": { "type": "string", "description": "Customer tier associated with the project", "enum": [ "free", "pro", "enterprise" ], "example": "enterprise" } } }, "VendorsResponse": { "type": "object", "properties": { "projectId": { "type": "string", "description": "Project identifier", "example": "67fcdb2b52ab9a99a5865f4d" }, "vendors": { "type": "array", "items": { "$ref": "#/components/schemas/Vendor" }, "description": "List of vendors for the project" }, "totalVendors": { "type": "integer", "description": "Total number of unique vendors", "example": 5 }, "categories": { "type": "array", "items": { "type": "string" }, "description": "All available vendor categories", "example": [ "Fonctionnels", "Analytics", "Marketing" ] }, "fetchedAt": { "type": "string", "format": "date-time", "description": "Timestamp when data was fetched", "example": "2025-09-12T14:30:00.000Z" } } }, "ConfigurationVendorsResponse": { "type": "object", "properties": { "projectId": { "type": "string", "description": "Project identifier", "example": "67fcdb2b52ab9a99a5865f4d" }, "configId": { "type": "string", "description": "Configuration identifier", "example": "67fcddc2673e895f81feb6c3" }, "configName": { "type": "string", "description": "Human-readable configuration name", "example": "fr-eu-14-04-2025" }, "vendors": { "type": "array", "items": { "$ref": "#/components/schemas/Vendor" }, "description": "List of vendors for the specific configuration" }, "totalVendors": { "type": "integer", "description": "Total number of vendors in this configuration", "example": 3 }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Vendor categories present in this configuration", "example": [ "Fonctionnels", "Analytics" ] }, "fetchedAt": { "type": "string", "format": "date-time", "description": "Timestamp when data was fetched", "example": "2025-09-12T14:30:00.000Z" } } }, "VendorCategoriesResponse": { "type": "object", "properties": { "projectId": { "type": "string", "description": "Project identifier", "example": "67fcdb2b52ab9a99a5865f4d" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/VendorCategory" }, "description": "Vendors organized by category" }, "totalCategories": { "type": "integer", "description": "Total number of categories", "example": 4 }, "totalVendors": { "type": "integer", "description": "Total number of vendors across all categories", "example": 12 }, "fetchedAt": { "type": "string", "format": "date-time", "description": "Timestamp when data was fetched", "example": "2025-09-12T14:30:00.000Z" } } }, "Vendor": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique vendor identifier", "example": "62fd02d250c4539d3456e350" }, "name": { "type": "string", "description": "Vendor technical name", "example": "googletagmanager" }, "title": { "type": "string", "description": "Vendor display name", "example": "Google Tag Manager" }, "description": { "type": "string", "description": "Short vendor description", "example": "Système de gestion de balisage" }, "longDescription": { "type": "string", "description": "Detailed vendor description", "example": "Mise en place d'un système de balisage pour traiter plus facilement les informations liées aux données." }, "category": { "type": "string", "description": "Primary vendor category", "example": "Fonctionnels, Gestion des étiquettes" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "All vendor categories", "example": [ "Fonctionnels", "Gestion des étiquettes" ] }, "type": { "type": "string", "description": "Vendor type classification", "example": "functional, tag_management" }, "domain": { "type": "string", "description": "Vendor domain/website", "example": "https://tagmanager.google.com/" }, "policyUrl": { "type": "string", "description": "Vendor privacy policy URL", "example": "https://marketingplatform.google.com/about/analytics/tag-manager/use-policy/" }, "isAxeptioVendor": { "type": "boolean", "description": "Whether this is an Axeptio-managed vendor", "example": true }, "image": { "$ref": "#/components/schemas/VendorImage" } } }, "VendorImage": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Image identifier", "example": "googletagmanager" }, "baseUrl": { "type": "string", "description": "Base imgix URL for the vendor image", "example": "https://axeptio.imgix.net/vendors/googletagmanager" }, "optimized": { "$ref": "#/components/schemas/OptimizedImages" }, "fallbackUrl": { "type": "string", "description": "Fallback favicon URL", "example": "https://favicons.axept.io/favicons?domain=tagmanager.google.com", "nullable": true } } }, "OptimizedImages": { "type": "object", "properties": { "small": { "type": "string", "description": "32x32px optimized image for mobile list views", "example": "https://axeptio.imgix.net/vendors/googletagmanager?w=32&h=32&fit=crop&auto=format,compress" }, "medium": { "type": "string", "description": "64x64px optimized image for mobile detail views", "example": "https://axeptio.imgix.net/vendors/googletagmanager?w=64&h=64&fit=crop&auto=format,compress" }, "large": { "type": "string", "description": "128x128px optimized image for high-DPI displays", "example": "https://axeptio.imgix.net/vendors/googletagmanager?w=128&h=128&fit=crop&auto=format,compress" } } }, "VendorCategory": { "type": "object", "properties": { "name": { "type": "string", "description": "Category name", "example": "Fonctionnels" }, "vendors": { "type": "array", "items": { "$ref": "#/components/schemas/Vendor" }, "description": "Vendors in this category" }, "count": { "type": "integer", "description": "Number of vendors in this category", "example": 3 } } }, "MobileEvent": { "type": "object", "required": [ "type", "timestamp", "metadata" ], "properties": { "type": { "type": "string", "description": "Event type identifier", "enum": [ "consent_displayed", "consent_accepted", "consent_rejected", "consent_partial", "page_view", "widget_opened", "widget_closed", "vendor_toggled", "category_toggled", "settings_opened", "privacy_policy_clicked", "pagehide", "pagevisible" ], "example": "consent_displayed" }, "timestamp": { "type": "string", "format": "date-time", "description": "Event timestamp in ISO 8601 format", "example": "2025-09-18T10:30:00.000Z" }, "metadata": { "$ref": "#/components/schemas/EventMetadata" }, "projectId": { "type": "string", "description": "Project identifier (optional if included in metadata)", "example": "67fcdb2b52ab9a99a5865f4d" }, "correlationId": { "type": "string", "description": "Correlation ID for tracking related events", "example": "consent-flow-abc123" }, "step": { "type": "object", "description": "Consent step information (for consent-related events)", "properties": { "name": { "type": "string", "example": "cookies" }, "identifier": { "type": "string", "example": "step_001" } } }, "deployment": { "type": "string", "description": "Deployment timestamp for configuration version tracking", "example": "2025-09-18T08:00:00.000Z" }, "source": { "type": "string", "description": "Event source identifier", "enum": [ "sdk-app", "sdk-web", "sdk-app-brands" ], "example": "sdk-app" } } }, "EventMetadata": { "type": "object", "properties": { "source": { "type": "string", "description": "Event source", "example": "sdk-app" }, "platform": { "type": "string", "description": "Mobile platform", "enum": [ "ios", "android", "react-native", "flutter", "web" ], "example": "ios" }, "appVersion": { "type": "string", "description": "Application version", "example": "1.2.3" }, "sdkVersion": { "type": "string", "description": "SDK version", "example": "2.1.0" }, "deviceInfo": { "type": "object", "description": "Device information (optional)", "properties": { "model": { "type": "string", "example": "iPhone14,2" }, "os": { "type": "string", "example": "iOS 16.0" }, "screenSize": { "type": "string", "example": "390x844" } } }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Consent categories (for consent events)", "example": [ "analytics", "marketing", "functional" ] }, "context": { "type": "string", "description": "Special context flags for event classification", "enum": [ "eventSentBeforeConfigLoaded", "configIsEmpty", "freeTrialBroken", "projectDeleted", "cookiesConfigEmpty" ], "example": "eventSentBeforeConfigLoaded" } } }, "EventSubmissionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the events were successfully processed", "example": true }, "processed": { "type": "integer", "description": "Number of events processed", "example": 2 }, "timestamp": { "type": "string", "format": "date-time", "description": "Processing timestamp", "example": "2025-09-18T10:30:16.000Z" }, "batchId": { "type": "string", "description": "Unique identifier for the batch submission", "example": "batch-abc123-def456" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Index of the event that caused the error" }, "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error message" } } }, "description": "Array of errors for failed events (only present if some events failed)" } } }, "ConsentSubmissionRequest1": { "type": "object", "required": [ "userToken", "preferences" ], "properties": { "userToken": { "type": "string", "description": "Unique identifier for the user providing consent", "example": "user-abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when consent was provided (ISO 8601 format). If not provided, server will use current time.", "example": "2025-09-18T10:30:00.000Z" }, "preferences": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "User consent preferences by category (e.g., analytics: true, marketing: false)", "example": { "analytics": true, "marketing": false, "functional": true } }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/MobileMetadata" } ], "description": "Additional metadata about the consent submission context" }, "source": { "type": "string", "description": "Source of the consent submission", "enum": [ "sdk-app", "sdk-web", "sdk-app-brands" ], "example": "sdk-app" }, "ipAddress": { "type": "string", "description": "IP address of the user (optional, for compliance tracking)", "example": "192.168.1.100" }, "userAgent": { "type": "string", "description": "User agent string (optional, for compliance tracking)", "example": "MyApp/1.2.3 (iOS 16.0; iPhone14,2)" } } }, "ConsentSubmissionResponse1": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the consent submission was successful", "example": true }, "consentId": { "type": "string", "description": "Unique identifier for the created consent record", "example": "consent-abc123-def456" }, "timestamp": { "type": "string", "format": "date-time", "description": "Server timestamp when the consent was processed", "example": "2025-09-18T10:30:01.000Z" }, "message": { "type": "string", "description": "Human-readable success message", "example": "Consent record created successfully" }, "version": { "type": "integer", "description": "Version number of the consent record (for tracking changes)", "example": 1 } } }, "ErrorResponse1": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code", "example": "unauthorized" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Missing or invalid authorization header" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "servers": [ { "url": "https://staging-api.axeptio.tech", "description": "Staging environment" }, { "url": "https://api.axeptio.tech", "description": "Production environment" } ] }