Control CoreDocs

🔧 Telemetry and License API Reference

Complete API documentation for Control Core telemetry and license management endpoints. These endpoints allow you to configure License Server connection, manage telemetry transmission, and check license status.

📌 Base URL

All endpoints are prefixed with /telemetry:

https://api.controlcore.yourcompany.com/api/v1/telemetry

📌 Authentication

All endpoints require JWT token authentication:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/config

🔧 Endpoints

Get Telemetry Configuration

Get current telemetry configuration settings.

Endpoint: GET /telemetry/config

Authentication: Required (JWT)

Response:

{
  "business_admin_url": "https://business-admin.controlcore.io",
  "api_key_configured": true,
  "enabled": true,
  "frequency": "twice_monthly",
  "encryption_enabled": true,
  "anonymization_enabled": true,
  "local_retention_days": 30,
  "last_transmission_at": "2025-11-12T10:00:00Z",
  "next_scheduled_at": "2025-11-15T02:00:00Z",
  "updated_at": "2025-11-10T08:30:00Z"
}

Example:

curl -X GET \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/config

Update Telemetry Configuration

Update telemetry configuration settings.

Endpoint: PUT /telemetry/config

Authentication: Required (JWT)

Request Body:

{
  "business_admin_url": "https://business-admin.controlcore.io",
  "api_key": "your-api-key-here",
  "enabled": true,
  "frequency": "twice_monthly",
  "encryption_enabled": true,
  "anonymization_enabled": true,
  "local_retention_days": 30
}

Frequency Options:

  • twice_monthly - 1st and 15th of each month (default)
  • weekly - Every Monday
  • monthly - 1st of each month
  • daily - Every day

Response: Same as GET /telemetry/config

Example:

curl -X PUT \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "business_admin_url": "https://business-admin.controlcore.io",
    "api_key": "your-api-key",
    "enabled": true,
    "frequency": "twice_monthly",
    "encryption_enabled": true,
    "anonymization_enabled": true,
    "local_retention_days": 30
  }' \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/config

Test License Server Connection

Test connection to License Server (cc-business-admin).

Endpoint: POST /telemetry/test-connection

Authentication: Required (JWT)

Response (Success):

{
  "status": "success",
  "message": "Successfully connected to License Admin server",
  "url": "https://business-admin.controlcore.io",
  "timestamp": "2025-11-12T10:00:00Z"
}

Response (Failure):

{
  "status": "failed",
  "message": "Failed to connect to License Admin server. Please verify URL and network connectivity.",
  "url": "https://business-admin.controlcore.io",
  "timestamp": "2025-11-12T10:00:00Z"
}

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/test-connection

Get Telemetry Preview

Get preview of current telemetry data that would be sent.

Endpoint: GET /telemetry/preview

Authentication: Required (JWT)

Response:

{
  "customer_id": "customer-123",
  "current_period": "2025-11-12",
  "policy_decision_count": 1250,
  "active_bouncer_count": 3,
  "total_events": 5432,
  "successful_decisions": 5200,
  "sandbox_events": 3200,
  "production_events": 2232,
  "health_status": "healthy",
  "deployment_version": "1.0.0",
  "tier": "custom"
}

Example:

curl -X GET \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/preview

Get Transmission History

Get history of telemetry transmissions.

Endpoint: GET /telemetry/history

Authentication: Required (JWT)

Query Parameters:

  • limit (optional): Number of records to return (default: 10)
  • skip (optional): Number of records to skip (default: 0)

Response:

[
  {
    "id": 1,
    "transmission_date": "2025-11-12T02:00:00Z",
    "status": "success",
    "records_sent": 5432,
    "response_code": 200,
    "response_message": "Transmission successful",
    "error_details": null,
    "retry_count": 0,
    "transmitted_at": "2025-11-12T02:00:15Z"
  },
  {
    "id": 2,
    "transmission_date": "2025-11-01T02:00:00Z",
    "status": "failed",
    "records_sent": 0,
    "response_code": 500,
    "response_message": "Server error",
    "error_details": "Connection timeout",
    "retry_count": 2,
    "transmitted_at": null
  }
]

Example:

curl -X GET \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "https://api.controlcore.yourcompany.com/api/v1/telemetry/history?limit=20&skip=0"

Trigger Manual Transmission

Manually trigger telemetry transmission to License Server.

Endpoint: POST /telemetry/send-now

Authentication: Required (JWT)

Response (Success):

{
  "status": "success",
  "message": "Telemetry transmitted successfully",
  "records_sent": 5432,
  "timestamp": "2025-11-12T10:00:00Z"
}

Response (Error):

{
  "detail": "Telemetry is not enabled"
}

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/send-now

Retry Failed Transmission

Retry a failed telemetry transmission.

Endpoint: POST /telemetry/history/{log_id}/retry

Authentication: Required (JWT)

Path Parameters:

  • log_id: ID of the transmission log to retry

Response (Success):

{
  "status": "success",
  "message": "Transmission retry successful",
  "log_id": 2,
  "retry_count": 3
}

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/history/2/retry

Get License Status

Get current license status and feature gate information.

Endpoint: GET /telemetry/license-status

Authentication: Required (JWT)

Response:

{
  "connected": true,
  "tier": "custom",
  "trial_expired": false,
  "trial_end_date": null,
  "trial_days_remaining": null,
  "license_admin_url": "https://business-admin.controlcore.io",
  "api_key_configured": true,
  "last_verification": "2025-11-12T02:00:00Z",
  "can_test_policies": true,
  "can_promote_to_production": true,
  "features_gated": false,
  "warning": null,
  "test_policies_message": "Policy testing enabled",
  "promote_message": "Production deployment enabled",
  "promote_warning": null
}

Example:

curl -X GET \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/license-status

Check Policy Testing Allowed

Check if policy testing is allowed (requires license connection).

Endpoint: GET /telemetry/license-check/test-policies

Authentication: Required (JWT)

Response (Allowed):

{
  "allowed": true,
  "reason": "License verified",
  "message": "Policy testing enabled"
}

Response (Not Allowed):

{
  "allowed": false,
  "reason": "License server connection required",
  "message": "Connect to Control Core License Server in General Settings (Telemetry tab) to enable policy testing"
}

Example:

curl -X GET \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/license-check/test-policies

Check Production Promotion Allowed

Check if production promotion is allowed (requires license connection).

Endpoint: GET /telemetry/license-check/promote-production

Authentication: Required (JWT)

Response (Allowed):

{
  "allowed": true,
  "reason": "License verified",
  "message": "Production deployment enabled"
}

Response (Not Allowed - Trial Expired):

{
  "allowed": false,
  "reason": "Trial expired",
  "message": "Trial period has expired. Please upgrade to continue production deployment.",
  "trial_end_date": "2025-11-01T00:00:00Z"
}

Example:

curl -X GET \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/license-check/promote-production

Get Telemetry Health

Get telemetry system health status.

Endpoint: GET /telemetry/health

Authentication: Required (JWT)

Response:

{
  "status": "healthy",
  "enabled": true,
  "connection_status": "connected",
  "license_admin_url": "https://business-admin.controlcore.io",
  "api_key_configured": true,
  "last_transmission_at": "2025-11-12T02:00:00Z",
  "next_scheduled_at": "2025-11-15T02:00:00Z",
  "frequency": "twice_monthly",
  "recent_errors": [],
  "message": "Telemetry system is healthy"
}

Health Status Values:

  • healthy - Connection active, recent successful transmission
  • warning - Connection active but last transmission > 7 days ago
  • unhealthy - Connection failed or transmission errors
  • disabled - Telemetry is disabled
  • not_configured - License Server connection not configured

Example:

curl -X GET \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/health

Get Scheduler Status

Get current status of telemetry scheduler.

Endpoint: GET /telemetry/scheduler-status

Authentication: Required (JWT)

Response:

{
  "scheduler_running": true,
  "enabled": true,
  "frequency": "twice_monthly",
  "next_scheduled_at": "2025-11-15T02:00:00Z",
  "last_transmission_at": "2025-11-12T02:00:00Z",
  "message": "Scheduler active"
}

Example:

curl -X GET \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.controlcore.yourcompany.com/api/v1/telemetry/scheduler-status

📌 License Server Webhook (Internal)

License Update Webhook

Endpoint: POST /telemetry/webhook/license-update

Authentication: Webhook signature (HMAC)

Purpose: Internal endpoint for License Server to update subscription tier.

Security: Webhook signature verification using HMAC-SHA256

Request Body:

{
  "customer_id": "customer-123",
  "subscription_tier": "custom",
  "trial_end_date": "2025-12-01T00:00:00Z",
  "subscription_status": "active",
  "effective_date": "2025-11-12T00:00:00Z",
  "webhook_signature": "hmac-sha256-signature"
}

Response:

{
  "status": "success",
  "message": "Subscription tier updated for 1 user(s)",
  "customer_id": "customer-123",
  "subscription_tier": "custom",
  "subscription_status": "active",
  "updated_users": 1,
  "timestamp": "2025-11-12T10:00:00Z"
}

Note: This endpoint is for internal use by License Server only. Webhook signature verification is required.

📌 Error Responses

All endpoints may return standard HTTP error codes:

400 Bad Request

{
  "detail": "Invalid frequency. Must be one of: twice_monthly, weekly, monthly, daily"
}

401 Unauthorized

{
  "detail": "Invalid webhook signature"
}

403 Forbidden

{
  "detail": "Connect to Control Core License Server in General Settings (Telemetry tab) to enable policy testing"
}

404 Not Found

{
  "detail": "Telemetry configuration not found"
}

500 Internal Server Error

{
  "detail": "Transmission error: Connection timeout"
}

🔒 Security Best Practices

API Key Security

  1. Store Securely: API keys are encrypted in the database
  2. Rotate Regularly: Change API keys periodically
  3. Use HTTPS: Always use HTTPS for API requests
  4. Limit Access: Restrict API key access to authorized users only

Webhook Security

  1. Signature Verification: Always verify webhook signatures
  2. HTTPS Only: Use HTTPS for webhook endpoints
  3. Rate Limiting: Implement rate limiting on webhook endpoints
  4. Audit Logging: Log all webhook attempts (success and failure)

Data Privacy

  1. Encryption: Enable data encryption for telemetry transmission
  2. Anonymization: Enable PII anonymization for compliance
  3. Retention: Configure appropriate data retention periods
  4. Access Control: Restrict telemetry configuration to admins only