Policies API

Policy endpoints allow you to define and evaluate Attribute-Based Access Control (ABAC) rules that govern what actions users and roles can perform on resources within your tenant.

Admin policy management (/policies, /policies/{id}) — Requires policy:read or policy:write permission.
Policy evaluation (/policies/evaluate) — Requires policy:read. Evaluate a policy decision at runtime against a provided context.

Base path: https://api.ithbat.io/api/v1/

Policy Object

Field	Type	Description
`id`	string	UUID of the policy
`tenantId`	string	UUID of the owning tenant
`name`	string	Human-readable policy name
`description`	string	Optional description of what the policy governs
`effect`	string	Decision when the policy matches: `allow` or `deny`
`conditions`	object	JSON object of attribute conditions that must be satisfied
`resources`	string[]	Resource URNs the policy applies to (e.g., `urn:ithbat:users:*`)
`actions`	string[]	Actions covered by this policy (e.g., `user:read`, `user:write`)
`priority`	integer	Evaluation order; higher values are evaluated first
`enabled`	boolean	Whether the policy is active
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last-modified timestamp

GET /api/v1/policies

Permission: policy:read

List all policies in the tenant.

curl "https://api.ithbat.io/api/v1/policies" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "policies": [
      {
        "id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "name": "Engineering Read Access",
        "description": "Allows engineers to read all user profiles within their department",
        "effect": "allow",
        "conditions": {
          "user.department": "engineering",
          "user.employmentStatus": "active"
        },
        "resources": ["urn:ithbat:users:*"],
        "actions": ["user:read"],
        "priority": 100,
        "enabled": true,
        "createdAt": "2026-01-10T08:00:00Z",
        "updatedAt": "2026-02-14T11:30:00Z"
      }
    ],
    "total": 1
  }
}

GET /api/v1/policies/{id}

Permission: policy:read

Retrieve a single policy by its UUID.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the policy

curl "https://api.ithbat.io/api/v1/policies/p1a2b3c4-d5e6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200 — Returns the full policy object.

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Policy does not exist in this tenant

POST /api/v1/policies/evaluate

Permission: policy:read

Evaluate whether a set of policies permits or denies a specific action against a resource for a given subject. The evaluation engine applies all matching enabled policies in priority order, with deny taking precedence over allow.

Request Body

Field	Type	Required	Description
`subject`	object	Yes	Attributes of the principal making the request (e.g., user ID, roles, department)
`action`	string	Yes	The action being attempted (e.g., `user:write`)
`resource`	string	Yes	URN of the resource being accessed (e.g., `urn:ithbat:users:a1b2c3d4`)
`context`	object	No	Additional environmental attributes (e.g., IP address, time of day)

curl -X POST "https://api.ithbat.io/api/v1/policies/evaluate" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "roles": ["support-engineer"],
      "department": "engineering"
    },
    "action": "user:read",
    "resource": "urn:ithbat:users:b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "context": {
      "ipAddress": "197.134.10.55",
      "userAgent": "Mozilla/5.0"
    }
  }'

Response 200

{
  "success": true,
  "data": {
    "decision": "allow",
    "matchedPolicies": [
      {
        "id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "name": "Engineering Read Access",
        "effect": "allow",
        "priority": 100
      }
    ],
    "reason": "Matched 1 allow policy and 0 deny policies"
  }
}

When no policies match, the decision defaults to deny:

{
  "success": true,
  "data": {
    "decision": "deny",
    "matchedPolicies": [],
    "reason": "No policies matched the request"
  }
}

POST /api/v1/policies

Permission: policy:write

Create a new access control policy in the tenant.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Human-readable policy name (must be unique in tenant)
`description`	string	No	Optional description
`effect`	string	Yes	`allow` or `deny`
`conditions`	object	Yes	Key-value attribute conditions that must all match
`resources`	string[]	Yes	Resource URNs (supports wildcards, e.g., `urn:ithbat:users:*`)
`actions`	string[]	Yes	Actions this policy covers
`priority`	integer	No	Evaluation priority (default: 0; higher = evaluated first)
`enabled`	boolean	No	Whether the policy is active on creation (default: true)

curl -X POST "https://api.ithbat.io/api/v1/policies" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HR Full Access",
    "description": "Grants HR admins full read and write access to all user profiles",
    "effect": "allow",
    "conditions": {
      "user.department": "hr",
      "user.roles": "hr-admin"
    },
    "resources": ["urn:ithbat:users:*"],
    "actions": ["user:read", "user:write"],
    "priority": 200,
    "enabled": true
  }'

Response 201

{
  "success": true,
  "data": {
    "id": "p9z8y7x6-w5v4-3210-uvwx-yz9876543210",
    "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
    "name": "HR Full Access",
    "description": "Grants HR admins full read and write access to all user profiles",
    "effect": "allow",
    "conditions": {
      "user.department": "hr",
      "user.roles": "hr-admin"
    },
    "resources": ["urn:ithbat:users:*"],
    "actions": ["user:read", "user:write"],
    "priority": 200,
    "enabled": true,
    "createdAt": "2026-03-19T10:00:00Z",
    "updatedAt": "2026-03-19T10:00:00Z"
  }
}

Error Codes

Code	HTTP	Description
`DUPLICATE_NAME`	409	A policy with this name already exists in the tenant
`VALIDATION_ERROR`	400	`effect` must be `allow` or `deny`; `resources` and `actions` must be non-empty

PUT /api/v1/policies/{id}

Permission: policy:write

Update an existing policy. All provided fields replace the current values.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the policy to update

Request Body

Field	Type	Required	Description
`name`	string	No	Updated policy name
`description`	string	No	Updated description
`effect`	string	No	`allow` or `deny`
`conditions`	object	No	Updated conditions object (replaces existing)
`resources`	string[]	No	Updated resource URNs (replaces existing)
`actions`	string[]	No	Updated actions (replaces existing)
`priority`	integer	No	Updated priority
`enabled`	boolean	No	Enable or disable the policy

curl -X PUT "https://api.ithbat.io/api/v1/policies/p9z8y7x6-w5v4-3210-uvwx-yz9876543210" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": 250,
    "actions": ["user:read", "user:write", "audit:read"]
  }'

Response 200 — Returns the updated policy object.

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Policy does not exist in this tenant
`DUPLICATE_NAME`	409	Another policy with this name already exists

DELETE /api/v1/policies/{id}

Permission: policy:write

Permanently delete a policy. Active policies are disabled before deletion; this action is irreversible.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the policy to delete

curl -X DELETE "https://api.ithbat.io/api/v1/policies/p9z8y7x6-w5v4-3210-uvwx-yz9876543210" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "Policy deleted"
}

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Policy does not exist in this tenant

POST /api/v1/policies/{id}/toggle

Permission: policy:write

Toggle the enabled state of a policy. If the policy is currently enabled it will be disabled, and vice versa.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the policy to toggle

curl -X POST "https://api.ithbat.io/api/v1/policies/p1a2b3c4-d5e6-7890-abcd-ef1234567890/toggle" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "enabled": false,
    "updatedAt": "2026-03-19T12:45:00Z"
  }
}

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Policy does not exist in this tenant

Policy Object​

GET /api/v1/policies​

GET /api/v1/policies/{id}​

POST /api/v1/policies/evaluate​

POST /api/v1/policies​

PUT /api/v1/policies/{id}​

DELETE /api/v1/policies/{id}​

POST /api/v1/policies/{id}/toggle​

Policy Object

GET /api/v1/policies

GET /api/v1/policies/{id}

POST /api/v1/policies/evaluate

POST /api/v1/policies

PUT /api/v1/policies/{id}

DELETE /api/v1/policies/{id}

POST /api/v1/policies/{id}/toggle