Policies API

The Policies API allows you to create, manage, and assign security policies that control DLP, network access, and device restrictions.

Policy Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "org-123",
  "name": "Engineering Team Policy",
  "description": "Security policy for engineering devices",
  "policy_data": {
    "dlp": {
      "clipboard_sharing": false,
      "screenshot_allowed": false,
      "print_allowed": true
    },
    "network": {
      "vpn_required": true,
      "allowed_domains": ["*.company.com", "github.com"]
    },
    "usb": {
      "allowed": false,
      "whitelist": []
    },
    "storage": {
      "encryption_required": true,
      "external_storage_allowed": false
    }
  },
  "version": 3,
  "active": true,
  "device_count": 45,
  "created_at": "2026-01-15T09:00:00Z",
  "updated_at": "2026-02-10T14:30:00Z"
}

Policy Types

DLP (Data Loss Prevention)

Setting Type Description
clipboard_sharing boolean Allow clipboard between work/personal
clipboard_direction string none, work_to_personal, personal_to_work, both
screenshot_allowed boolean Allow screenshots in work profile
print_allowed boolean Allow printing from work apps
sensitive_data_patterns array Regex patterns for sensitive data detection

Network

Setting Type Description
vpn_required boolean Require VPN for all traffic
vpn_always_on boolean Block traffic if VPN disconnects
allowed_domains array Whitelist of allowed domains
blocked_domains array Blacklist of blocked domains
split_tunnel boolean Allow split tunneling

USB Device Control

Setting Type Description
allowed boolean Allow any USB devices
whitelist array Allowed vendor:product IDs
allowed_classes array Allowed USB device classes (e.g., HID, audio)
audit_only boolean Log but don't block

Storage

Setting Type Description
encryption_required boolean Require disk encryption
external_storage_allowed boolean Allow external storage access
cloud_sync_allowed boolean Allow cloud storage sync
max_file_size_mb integer Max file size for transfers

List Policies

GET /api/v1/policies

GET /api/v1/policies?page=1&page_size=20
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response

{
  "data": [
    {
      "id": "policy-123",
      "name": "Default Security Policy",
      "device_count": 45,
      "active": true,
      "created_at": "2026-01-15T09:00:00Z"
    },
    {
      "id": "policy-456",
      "name": "Engineering Team Policy",
      "device_count": 12,
      "active": true,
      "created_at": "2026-02-01T10:00:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "page_size": 20
}

Get Policy

GET /api/v1/policies/:id

GET /api/v1/policies/policy-123
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response

Returns the full policy object as shown above.

Create Policy

POST /api/v1/policies

POST /api/v1/policies
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "name": "Marketing Team Policy",
  "description": "Policy for marketing department",
  "policy_data": {
    "dlp": {
      "clipboard_sharing": true,
      "clipboard_direction": "personal_to_work",
      "screenshot_allowed": false,
      "print_allowed": true
    },
    "network": {
      "vpn_required": true,
      "vpn_always_on": false,
      "allowed_domains": ["*.company.com", "*.google.com", "*.salesforce.com"]
    },
    "usb": {
      "allowed": true,
      "allowed_classes": ["hid", "audio"],
      "audit_only": false
    },
    "storage": {
      "encryption_required": true,
      "external_storage_allowed": false,
      "cloud_sync_allowed": true
    }
  }
}

Response

HTTP/1.1 201 Created

{
  "id": "policy-789",
  "name": "Marketing Team Policy",
  "version": 1,
  "active": true,
  "device_count": 0,
  "created_at": "2026-02-12T10:45:00Z"
}

Update Policy

PUT /api/v1/policies/:id

Update an existing policy. This creates a new version.

PUT /api/v1/policies/policy-789
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "name": "Marketing Team Policy",
  "description": "Updated policy for marketing department",
  "policy_data": {
    "dlp": {
      "clipboard_sharing": false,
      "screenshot_allowed": false
    }
  }
}

Response

{
  "id": "policy-789",
  "name": "Marketing Team Policy",
  "version": 2,
  "updated_at": "2026-02-12T11:00:00Z"
}
Versioning: Policy updates create new versions. Devices automatically receive the latest version on their next check-in.

Delete Policy

DELETE /api/v1/policies/:id

Delete a policy. Devices assigned to this policy will fall back to the default policy.

DELETE /api/v1/policies/policy-789
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response

HTTP/1.1 200 OK

{
  "message": "policy deleted",
  "affected_devices": 12,
  "fallback_policy": "policy-default"
}

Policy Devices

GET /api/v1/policies/:id/devices

List devices assigned to a policy.

{
  "data": [
    {
      "id": "device-123",
      "device_name": "John's Laptop",
      "status": "online",
      "policy_version": 2,
      "last_sync": "2026-02-12T10:30:00Z"
    }
  ],
  "total": 12
}

Default Policy

GET /api/v1/policies/default

Get the organization's default policy (assigned to new devices).

PUT /api/v1/policies/default

Set a policy as the organization default.

PUT /api/v1/policies/default
Content-Type: application/json

{
  "policy_id": "policy-123"
}

Policy Templates

GET /api/v1/policies/templates

List available policy templates for quick setup.

{
  "data": [
    {
      "id": "template-strict",
      "name": "Strict Security",
      "description": "Maximum security for sensitive data",
      "recommended_for": ["healthcare", "finance"]
    },
    {
      "id": "template-balanced",
      "name": "Balanced",
      "description": "Balance between security and usability",
      "recommended_for": ["general"]
    },
    {
      "id": "template-byod",
      "name": "BYOD Friendly",
      "description": "Optimized for personal device usage",
      "recommended_for": ["remote", "contractors"]
    }
  ]
}

POST /api/v1/policies/from-template

Create a policy from a template.

POST /api/v1/policies/from-template
Content-Type: application/json

{
  "template_id": "template-strict",
  "name": "My Strict Policy",
  "customizations": {
    "dlp": {
      "print_allowed": true
    }
  }
}

Policy Validation

POST /api/v1/policies/validate

Validate a policy configuration without creating it.

POST /api/v1/policies/validate
Content-Type: application/json

{
  "policy_data": {
    "dlp": {
      "clipboard_sharing": "invalid"
    }
  }
}

Response (Invalid)

HTTP/1.1 400 Bad Request

{
  "valid": false,
  "errors": [
    {
      "field": "dlp.clipboard_sharing",
      "message": "must be a boolean",
      "received": "invalid"
    }
  ]
}

Policy History

GET /api/v1/policies/:id/history

View version history for a policy.

{
  "data": [
    {
      "version": 3,
      "changed_by": "admin@example.com",
      "changed_at": "2026-02-10T14:30:00Z",
      "changes": ["Updated DLP settings"]
    },
    {
      "version": 2,
      "changed_by": "admin@example.com",
      "changed_at": "2026-02-05T10:00:00Z",
      "changes": ["Added USB restrictions"]
    }
  ]
}

Next Steps