Policy Management

Overview

The Policy Management API provides endpoints for defining and managing access control policies. You can set condition-based rules and simulate access control behavior.

Endpoint List

Method	Endpoint	Description
GET	/api/admin/policies	List policies
GET	/api/admin/policies/:id	Get policy details
POST	/api/admin/policies	Create policy
PUT	/api/admin/policies/:id	Update policy
DELETE	/api/admin/policies/:id	Delete policy
POST	/api/admin/policies/simulate	Simulate policy
GET	/api/admin/policies/condition-types	List condition types

---

List Policies

Retrieve a list of policies within the tenant.

Endpoint

GET /api/admin/policies

Query Parameters

Parameter	Type	Required	Description
limit	integer	-	Number of items (default: 20, max: 100)
cursor	string	-	Pagination cursor
status	string	-	Filter by status (active, inactive)
resource	string	-	Filter by resource

Request Example

curl -X GET "https://{tenant-domain}/api/admin/policies?status=active" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "policy_abc123",
      "name": "admin-only-settings",
      "description": "Only administrators can change settings",
      "status": "active",
      "effect": "deny",
      "priority": 100,
      "resource": "settings:*",
      "created_at": 1705881600,
      "updated_at": 1705968000
    },
    {
      "id": "policy_def456",
      "name": "office-hours-access",
      "description": "Access only during office hours",
      "status": "active",
      "effect": "allow",
      "priority": 50,
      "resource": "documents:*",
      "created_at": 1705968000,
      "updated_at": 1706054400
    }
  ],
  "total": 10,
  "cursor": null
}

---

Get Policy Details

Retrieve detailed information for a specified policy.

Endpoint

GET /api/admin/policies/:id

Path Parameters

Parameter	Type	Required	Description
id	string	✓	Policy ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/policies/policy_def456" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "policy_def456",
  "name": "office-hours-access",
  "description": "Access only during office hours",
  "status": "active",
  "effect": "allow",
  "priority": 50,
  "resource": "documents:*",
  "actions": ["read", "write"],
  "conditions": [
    {
      "type": "time_range",
      "operator": "between",
      "value": {
        "start": "09:00",
        "end": "18:00",
        "timezone": "America/New_York"
      }
    },
    {
      "type": "day_of_week",
      "operator": "in",
      "value": ["monday", "tuesday", "wednesday", "thursday", "friday"]
    },
    {
      "type": "ip_range",
      "operator": "in",
      "value": ["192.168.1.0/24", "10.0.0.0/8"]
    }
  ],
  "subjects": {
    "roles": ["employee"],
    "exclude_roles": ["contractor"]
  },
  "created_at": 1705968000,
  "updated_at": 1706054400
}

---

Create Policy

Create a new policy.

Endpoint

POST /api/admin/policies

Request Body

Field	Type	Required	Description
name	string	✓	Policy name
description	string	-	Description
effect	string	✓	Effect (allow, deny)
priority	integer	-	Priority (higher evaluated first, default: 0)
resource	string	✓	Target resource (wildcards allowed)
actions	string[]	-	Target actions
conditions	object[]	-	List of conditions
subjects	object	-	Target subjects (roles, users, etc.)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/policies" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mfa-required-for-admin",
    "description": "MFA required for admin access",
    "effect": "deny",
    "priority": 200,
    "resource": "admin:*",
    "actions": ["*"],
    "conditions": [
      {
        "type": "mfa_verified",
        "operator": "equals",
        "value": false
      }
    ],
    "subjects": {
      "roles": ["tenant_admin", "system_admin"]
    }
  }'

Response Example

{
  "id": "policy_xyz789",
  "name": "mfa-required-for-admin",
  "status": "active",
  "effect": "deny",
  "priority": 200,
  "resource": "admin:*",
  "created_at": 1706140800
}

---

Update Policy

Update an existing policy.

Endpoint

PUT /api/admin/policies/:id

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/policies/policy_def456" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Access only during office hours (9:00-19:00)",
    "conditions": [
      {
        "type": "time_range",
        "operator": "between",
        "value": {
          "start": "09:00",
          "end": "19:00",
          "timezone": "America/New_York"
        }
      }
    ]
  }'

---

Delete Policy

Delete a policy.

Endpoint

DELETE /api/admin/policies/:id

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/policies/policy_abc123" \
  -H "Authorization: Bearer {token}"

Response

Status code 204 No Content (no body)

---

Policy Simulation

Simulate how policies would be evaluated in a specific context.

Endpoint

POST /api/admin/policies/simulate

Request Body

Field	Type	Required	Description
resource	string	✓	Resource
action	string	✓	Action
subject	object	✓	Subject (user information)
context	object	-	Additional context (time, IP, etc.)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/policies/simulate" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "documents:report_2024",
    "action": "read",
    "subject": {
      "user_id": "usr_abc123",
      "roles": ["employee"],
      "attributes": {
        "department": "Engineering"
      }
    },
    "context": {
      "ip_address": "192.168.1.100",
      "time": "2024-01-22T14:30:00-05:00",
      "mfa_verified": true
    }
  }'

Response Example

{
  "decision": "allow",
  "evaluated_policies": [
    {
      "id": "policy_def456",
      "name": "office-hours-access",
      "effect": "allow",
      "matched": true,
      "conditions_met": [
        {
          "type": "time_range",
          "result": true,
          "reason": "14:30 is within 09:00-18:00"
        },
        {
          "type": "day_of_week",
          "result": true,
          "reason": "monday is in allowed days"
        },
        {
          "type": "ip_range",
          "result": true,
          "reason": "192.168.1.100 is in 192.168.1.0/24"
        }
      ]
    }
  ],
  "reason": "Policy 'office-hours-access' allowed access"
}

---

List Condition Types

Retrieve available condition types and their configuration options. Used for UI construction.

Endpoint

GET /api/admin/policies/condition-types

Request Example

curl -X GET "https://{tenant-domain}/api/admin/policies/condition-types" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "condition_types": [
    {
      "type": "time_range",
      "display_name": "Time Range",
      "description": "Specify accessible time periods",
      "operators": ["between", "not_between"],
      "value_schema": {
        "type": "object",
        "properties": {
          "start": { "type": "string", "format": "time" },
          "end": { "type": "string", "format": "time" },
          "timezone": { "type": "string" }
        }
      }
    },
    {
      "type": "day_of_week",
      "display_name": "Day of Week",
      "description": "Specify accessible days",
      "operators": ["in", "not_in"],
      "value_schema": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"]
        }
      }
    },
    {
      "type": "ip_range",
      "display_name": "IP Address Range",
      "description": "Allowed IP address ranges",
      "operators": ["in", "not_in"],
      "value_schema": {
        "type": "array",
        "items": { "type": "string", "format": "cidr" }
      }
    },
    {
      "type": "mfa_verified",
      "display_name": "MFA Verification",
      "description": "Whether MFA is verified",
      "operators": ["equals"],
      "value_schema": { "type": "boolean" }
    },
    {
      "type": "user_attribute",
      "display_name": "User Attribute",
      "description": "Check user attribute values",
      "operators": ["equals", "not_equals", "in", "not_in", "greater_than", "less_than"],
      "value_schema": {
        "type": "object",
        "properties": {
          "attribute": { "type": "string" },
          "value": {}
        }
      }
    },
    {
      "type": "geo_location",
      "display_name": "Geographic Location",
      "description": "Access source country/region",
      "operators": ["in", "not_in"],
      "value_schema": {
        "type": "array",
        "items": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" }
      }
    }
  ]
}

---

Policy Evaluation Priority

1. Priority: Policies with higher priority values are evaluated first
2. Effect: For the same priority, deny takes precedence over allow
3. Specificity: More specific resource specifications take precedence

Example:
priority: 200, effect: deny  -> Highest priority
priority: 200, effect: allow -> Second
priority: 100, effect: deny  -> Third
priority: 100, effect: allow -> Fourth