Policies API

Policies define security rules and enforcement mechanisms for the NeoSC platform. Admins can view and toggle policies to control access, network security, and session behavior.

Policy Model

string

Unique policy identifier (e.g., “pol-mfa-required”)

name

string

Human-readable policy name

description

string

Detailed description of what the policy enforces

type

string

Policy category: "access", "network", "session"

rules

array

Array of rule strings describing specific enforcement actions

enabled

boolean

Whether the policy is currently active (defaults to true)

created_at

datetime

Timestamp when the policy was created (ISO 8601 format)

List Policies

Retrieve all security policies.

curl https://your-domain.com/api/policies \
  -H "Authorization: Bearer your-token-here"

Response

[
  {
    "id": "pol-mfa-required",
    "name": "MFA Required",
    "description": "Enforce multi-factor authentication for all users",
    "type": "access",
    "rules": [
      "Require MFA for login",
      "WebAuthn preferred",
      "TOTP as fallback"
    ],
    "enabled": true,
    "created_at": "2026-03-01T10:00:00.000Z"
  },
  {
    "id": "pol-network-zero-trust",
    "name": "Zero Trust Network",
    "description": "All connections through encrypted NetBird tunnels",
    "type": "network",
    "rules": [
      "No direct connections",
      "WireGuard encryption",
      "Identity verification"
    ],
    "enabled": true,
    "created_at": "2026-03-01T10:00:00.000Z"
  },
  {
    "id": "pol-session-recording",
    "name": "Session Recording",
    "description": "Record all workspace sessions for audit",
    "type": "session",
    "rules": [
      "Record screen activity",
      "Log keystrokes for audit",
      "30-day retention"
    ],
    "enabled": true,
    "created_at": "2026-03-01T10:00:00.000Z"
  }
]

Default Policies

If no policies exist in the database, the API automatically creates 3 default policies:

1. MFA Required (Access Policy)

ID: pol-mfa-required
Type: access
Rules:
- Require MFA for login
- WebAuthn preferred
- TOTP as fallback

2. Zero Trust Network (Network Policy)

ID: pol-network-zero-trust
Type: network
Rules:
- No direct connections
- WireGuard encryption
- Identity verification

3. Session Recording (Session Policy)

ID: pol-session-recording
Type: session
Rules:
- Record screen activity
- Log keystrokes for audit
- 30-day retention

Toggle Policy

Enable or disable a policy. This endpoint toggles the current state.

curl -X PATCH https://your-domain.com/api/policies/pol-mfa-required \
  -H "Authorization: Bearer your-token-here"

Response

{
  "message": "Policy disabled",
  "enabled": false
}

Or when enabling:

{
  "message": "Policy enabled",
  "enabled": true
}

Automatic Actions

When a policy is toggled:

Policy enabled status is flipped (true → false or false → true)
Audit log entry is created: "toggle_policy" action
Details include whether policy was enabled or disabled

Error Responses

404

error

{
  "detail": "Policy not found"
}

401

error

{
  "detail": "Not authenticated"
}

Policy Types

Access Policies

Control authentication and authorization:

Multi-factor authentication requirements
Password policies
Session timeout rules
Login attempt limits

Example: pol-mfa-required

Network Policies

Define network security rules:

VPN/tunnel requirements
Encryption standards
IP allowlists/denylists
Zero-trust networking

Example: pol-network-zero-trust

Session Policies

Govern workspace session behavior:

Session recording
Activity logging
Idle timeout
Data retention

Example: pol-session-recording

Example: Policy Management Dashboard

import requests
from typing import List, Dict

BASE_URL = "https://your-domain.com/api"

class PolicyManager:
    def __init__(self, token: str):
        self.headers = {"Authorization": f"Bearer {token}"}
    
    def list_policies(self) -> List[Dict]:
        """Get all policies"""
        response = requests.get(
            f"{BASE_URL}/policies",
            headers=self.headers
        )
        return response.json()
    
    def toggle_policy(self, policy_id: str) -> Dict:
        """Toggle a policy on/off"""
        response = requests.patch(
            f"{BASE_URL}/policies/{policy_id}",
            headers=self.headers
        )
        return response.json()
    
    def get_enabled_policies(self) -> List[Dict]:
        """Get only enabled policies"""
        policies = self.list_policies()
        return [p for p in policies if p['enabled']]
    
    def get_policies_by_type(self, policy_type: str) -> List[Dict]:
        """Get policies of a specific type"""
        policies = self.list_policies()
        return [p for p in policies if p['type'] == policy_type]
    
    def display_policy_status(self):
        """Display all policies with their status"""
        policies = self.list_policies()
        
        print("\n=== Security Policies ===")
        for policy in policies:
            status = "✓ ENABLED" if policy['enabled'] else "✗ DISABLED"
            print(f"\n{status} - {policy['name']}")
            print(f"  Type: {policy['type'].upper()}")
            print(f"  Description: {policy['description']}")
            print(f"  Rules:")
            for rule in policy['rules']:
                print(f"    - {rule}")

# Usage
manager = PolicyManager(token="your-token-here")

# Display all policies
manager.display_policy_status()

# Get only access policies
access_policies = manager.get_policies_by_type("access")
print(f"\nAccess policies: {len(access_policies)}")

# Disable MFA requirement (not recommended!)
result = manager.toggle_policy("pol-mfa-required")
print(f"\n{result['message']}")

Example: Audit Policy Changes

import requests

def audit_policy_changes(token: str):
    """View all policy change events in audit logs"""
    headers = {"Authorization": f"Bearer {token}"}
    
    # Get audit logs
    logs = requests.get(
        "https://your-domain.com/api/audit-logs",
        headers=headers
    ).json()
    
    # Filter for policy actions
    policy_logs = [
        log for log in logs 
        if log['action'] == 'toggle_policy'
    ]
    
    print("\n=== Policy Change History ===")
    for log in policy_logs:
        print(f"\n{log['timestamp']}")
        print(f"  User: {log['user_email']}")
        print(f"  Resource: {log['resource']}")
        print(f"  Action: {log['details']}")
        print(f"  Success: {log['success']}")

# Usage
audit_policy_changes(token="your-token-here")

Security Best Practices

Critical Policies: The following policies should remain enabled in production:

MFA Required: Protects against credential theft
Zero Trust Network: Ensures all connections are encrypted
Session Recording: Required for compliance and audit trails

Policy changes are logged in audit logs. Always review audit logs after making policy changes to ensure they were applied correctly.

Current Limitations

The current API provides toggle-only functionality. The following operations are not yet implemented:

Creating custom policies (POST /policies)
Updating policy rules (PUT /policies/{id})
Deleting policies (DELETE /policies/{id})
Policy versioning
Policy templates

Integration with Audit Logs

All policy changes are tracked in audit logs:

# View audit logs
curl https://your-domain.com/api/audit-logs \
  -H "Authorization: Bearer your-token-here"

Policy-related audit log entries:

{
  "id": "log-123",
  "user_id": "user-456",
  "user_email": "admin@example.com",
  "action": "toggle_policy",
  "resource": "policy:pol-mfa-required",
  "details": "Policy disabled",
  "timestamp": "2026-03-05T14:30:00.000Z",
  "success": true
}

Audit Logs

View policy change history

Users

User authentication affected by access policies

Sessions

Sessions governed by session policies

Workspaces

Workspaces protected by network policies

Getting Started

Endpoints

Policies

Policies API

Policy Model

List Policies

Response

Default Policies

1. MFA Required (Access Policy)

2. Zero Trust Network (Network Policy)

3. Session Recording (Session Policy)

Toggle Policy

Response

Automatic Actions

Error Responses

Policy Types

Access Policies

Network Policies

Session Policies

Example: Policy Management Dashboard

Example: Audit Policy Changes

Security Best Practices

Current Limitations

Integration with Audit Logs

Audit Logs

Users

Sessions

Workspaces

Build docs developers (and LLMs) love

Getting Started

Endpoints

​Policies API

​Policy Model

​List Policies

​Response

​Default Policies

​1. MFA Required (Access Policy)

​2. Zero Trust Network (Network Policy)

​3. Session Recording (Session Policy)

​Toggle Policy

​Response

​Automatic Actions

​Error Responses

​Policy Types

​Access Policies

​Network Policies

​Session Policies

​Example: Policy Management Dashboard

​Example: Audit Policy Changes

​Security Best Practices

​Current Limitations

​Integration with Audit Logs

​Related Endpoints

Audit Logs

Users

Sessions

Workspaces

Build docs developers (and LLMs) love

Policies API

Policy Model

List Policies

Response

Default Policies

1. MFA Required (Access Policy)

2. Zero Trust Network (Network Policy)

3. Session Recording (Session Policy)

Toggle Policy

Response

Automatic Actions

Error Responses

Policy Types

Access Policies

Network Policies

Session Policies

Example: Policy Management Dashboard

Example: Audit Policy Changes

Security Best Practices

Current Limitations

Integration with Audit Logs

Related Endpoints