Pradeo Security API

Appearance

Common Data Models ​

This document describes the common data models and schemas used throughout the Pradeo Security API.

Device ​

The Device model represents a managed mobile device.

json
{
  "id": "<device-id>",
  "name": "John's iPhone",
  "deviceGroupId": "<device-group-id>",
  "platform": "ios",
  "osVersion": "17.2",
  "manufacturer": "Apple",
  "model": "iPhone 14",
  "serialNumber": "DEVICE_SERIAL",
  "imei": "123456789012345",
  "imsi": "310150123456789",
  "phoneNumber": "+1234567890",
  "ipAddress": "192.168.1.100",
  "agentVersion": "3.2.1",
  "agentStatus": "online",
  "lastSyncAt": "2024-01-15T10:30:00Z",
  "enrolledAt": "2024-01-01T09:00:00Z",
  "riskLevel": "low",
  "securityStatus": "secured",
  "tags": ["<tag-id>", "<tag-id>"],
  "customFields": {}
}

Device Group ​

Groups devices for bulk management and policy application.

json
{
  "id": "<device-group-id>",
  "name": "Sales Team",
  "description": "Sales department devices",
  "deviceCount": 42,
  "parentGroupId": null,
  "childGroups": [],
  "agentConfigurationId": "<agent-configuration-id>",
  "createdAt": "2024-01-01T09:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Application ​

Represents a mobile application.

json
{
  "id": "<application-id>",
  "packageName": "com.example.app",
  "name": "Example Application",
  "version": "1.2.3",
  "versionCode": 123,
  "publisher": "Example Company",
  "firstSeen": "2024-01-01T09:00:00Z",
  "lastSeen": "2024-01-15T10:30:00Z",
  "riskLevel": "medium",
  "isMalicious": false,
  "category": "social",
  "size": 45678900,
  "signature": "ABC123DEF456",
  "md5": "<md5>",
  "sha1": "<sha1>",
  "sha256": "<sha256>"
}

Application Report ​

Detailed analysis report for an application.

json
{
  "id": "<application-report-id>",
  "applicationId": "<application-id>",
  "status": "completed",
  "riskLevel": "high",
  "vulnerabilities": 3,
  "permissions": 24,
  "suspiciousFeatures": 5,
  "analyses": {
    "antivirusScan": {
      "status": "clean",
      "engineVersion": "2024-01-15",
      "detections": []
    },
    "staticAnalysis": {
      "suspiciousApis": 5,
      "encryptedContent": true,
      "dynamicCodeLoading": true
    },
    "dynamicAnalysis": {
      "dataAccess": ["contacts", "location"],
      "networkCalls": 42,
      "fileOperations": 15
    }
  },
  "createdAt": "2024-01-15T09:00:00Z",
  "completedAt": "2024-01-15T10:30:00Z"
}

Access Key ​

Credentials for API authentication.

json
{
  "id": "<access-key-id>",
  "key": "<access-key>",
  "description": "My Integration Key",
  "enabled": true,
  "companyId": "<company-id>",
  "createdAt": "2024-01-15T10:00:00Z",
  "lastUsedAt": "2024-01-15T10:30:00Z",
  "createdBy": "<user-id>"
}

Secret Key ​

Personal secret key for API authentication.

json
{
  "id": "<secret-key-id>",
  "key": "<secret-key>",
  "description": "My Secret Key",
  "enabled": true,
  "userId": "<user-id>",
  "createdAt": "2024-01-15T10:00:00Z",
  "lastUsedAt": "2024-01-15T10:30:00Z"
}

Detection Policy ​

Defines what threats to detect.

json
{
  "id": "<detection-policy-id>",
  "name": "Standard Detection",
  "description": "Standard threat detection policy",
  "enabled": true,
  "rules": [
    {
      "id": "<detection-rule-id>",
      "type": "malware",
      "severity": "high",
      "enabled": true
    },
    {
      "id": "<detection-rule-id>",
      "type": "suspicious_behavior",
      "severity": "medium",
      "enabled": true
    }
  ],
  "createdAt": "2024-01-01T09:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Response Policy ​

Defines how to respond to detected threats.

json
{
  "id": "<response-policy-id>",
  "name": "Corporate Response",
  "description": "Response policy for corporate devices",
  "enabled": true,
  "rulesets": [
    {
      "id": "<ruleset-id>",
      "name": "High Severity Response",
      "order": 1,
      "rules": [
        {
          "type": "<device-rule-id>",
          "condition": "severity = high",
          "action": "lock_device"
        },
        {
          "type": "<device-application-rule-id>",
          "condition": "<detection-policy-id> = malware",
          "action": "uninstall_app"
        }
      ]
    }
  ],
  "createdAt": "2024-01-01T09:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Agent Configuration ​

Settings for device agents.

json
{
  "id": "<agent-configuration-id>",
  "name": "Default Configuration",
  "description": "Default agent configuration",
  "monitoring": {
    "enableAppMonitoring": true,
    "enableLocationTracking": false,
    "enableNetworkMonitoring": true,
    "scanFrequency": "daily"
  },
  "security": {
    "enableMalwareDetection": true,
    "enableVulnerabilityDetection": true,
    "enablePhishingDetection": true
  },
  "privacy": {
    "enablePrivacyMonitoring": true,
    "dataAccessAlert": true
  },
  "createdAt": "2024-01-01T09:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

User ​

Represents a user in the system.

json
{
  "id": "<user-id>",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "roles": ["<role-id>", "<role-id>"],
  "enabled": true,
  "lastLoginAt": "2024-01-15T10:30:00Z",
  "createdAt": "2024-01-01T09:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Company ​

Represents a company/organization.

json
{
  "id": "<company-id>",
  "name": "Acme Corporation",
  "description": "A tech company",
  "website": "https://acme.com",
  "timezone": "UTC",
  "country": "US",
  "licenseType": "enterprise",
  "subscriptionStatus": "active",
  "maxDevices": 1000,
  "currentDevices": 450,
  "createdAt": "2024-01-01T09:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Enrollment Code ​

Code for device enrollment.

json
{
  "id": "<enrollment-code-id>",
  "code": "ENROLL-ABC123-XYZ789",
  "deviceGroupId": "<device-group-id>",
  "expiresAt": "2024-02-15T10:00:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "usedCount": 5,
  "maxUses": 100,
  "isActive": true
}

Device Status Event ​

Represents a status change event for a device.

json
{
  "id": "<event-id>",
  "deviceId": "<device-id>",
  "eventType": "status_changed",
  "previousStatus": "offline",
  "newStatus": "online",
  "timestamp": "2024-01-15T10:30:00Z",
  "details": {
    "reason": "Agent connected",
    "ipAddress": "192.168.1.100"
  }
}

Message ​

Represents a message sent to a device or group.

json
{
  "id": "<message-id>",
  "deviceId": "<device-id>",
  "title": "Security Alert",
  "body": "A suspicious app was detected",
  "priority": "high",
  "type": "alert",
  "status": "delivered",
  "sentAt": "2024-01-15T10:00:00Z",
  "deliveredAt": "2024-01-15T10:05:00Z",
  "readAt": "2024-01-15T10:10:00Z"
}

Tag ​

Represents a label for organizing devices.

json
{
  "id": "<tag-id>",
  "name": "executive",
  "color": "#FF5733",
  "description": "Executive devices",
  "deviceCount": 15,
  "createdAt": "2024-01-01T09:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Statistics ​

Fleet-wide statistics snapshot.

json
{
  "totalDevices": 450,
  "onlineDevices": 440,
  "offlineDevices": 10,
  "securedDevices": 445,
  "atRiskDevices": 5,
  "maliciousDevices": 0,
  "totalApplications": 3200,
  "maliciousApplications": 2,
  "suspiciousApplications": 15,
  "vulnerableApplications": 42,
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response ​

Standard error response format.

json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required parameter: id",
    "details": {
      "field": "id",
      "reason": "required"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/v2/devices/invalid"
}

Pagination ​

Paginated response format.

json
{
  "total": 450,
  "count": 50,
  "skip": 0,
  "take": 50,
  "items": [
    {
      /* item 1 */
    },
    {
      /* item 2 */
    }
  ]
}

Authentication Token Response ​

Response from authentication endpoint.

json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_xxxxxxxxxxxxxxxx",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}