Policy Endpoints

Policies define access control rules using a policy-based access control (PBAC) model. Each policy specifies subjects (identities), resources, actions, conditions, and an effect (ALLOW or DENY). Policies are evaluated in priority order, with DENY taking precedence over ALLOW at the same priority level.

List Policies

Retrieve all policies for your organization.

GET /api/v1/policies

Query Parameters

Parameter	Type	Description
active	boolean	If true, return only active policies. If false, return only inactive policies.

Example Request

curl -X GET "https://app.veraid.io/api/v1/policies?active=true" \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "data": [
    {
      "id": "pol_abc123",
      "name": "Production Secrets - Business Hours Only",
      "description": "Restrict production secret access to business hours for non-emergency identities",
      "priority": 10,
      "effect": "DENY",
      "subjects": [
        { "type": "tag", "value": "non-emergency" }
      ],
      "resources": [
        { "type": "path", "value": "secrets/production/*" }
      ],
      "actions": ["read", "list"],
      "conditions": [
        {
          "type": "time",
          "operator": "outside",
          "value": {
            "start": "08:00",
            "end": "18:00",
            "timezone": "America/New_York",
            "days": ["monday", "tuesday", "wednesday", "thursday", "friday"]
          }
        }
      ],
      "active": true,
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-03-01T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "totalPages": 1,
    "hasMore": false
  }
}

---

Create Policy

Create a new access control policy.

POST /api/v1/policies

Request Body

Field	Type	Required	Description
name	string	Yes	Policy name (2-200 characters)
description	string	No	Human-readable description of the policy’s purpose
priority	number	No	Priority for evaluation order (lower = higher priority, default: 100)
subjects	object[]	Yes	Identities or groups this policy applies to
resources	object[]	Yes	Resources this policy governs
actions	string[]	Yes	Actions this policy controls (e.g., read, write, delete, execute)
conditions	object[]	No	Additional conditions that must be met for the policy to apply
effect	string	Yes	Policy effect: ALLOW or DENY

Subject Types

Type	Description	Example
identity	Specific identity by ID	{ "type": "identity", "value": "id_abc123" }
tag	All identities with a tag	{ "type": "tag", "value": "production" }
type	All identities of a type	{ "type": "type", "value": "CI_CD" }
all	All identities	{ "type": "all", "value": "*" }

Condition Types

Type	Description
time	Time-of-day and day-of-week restrictions
ip	Source IP address or CIDR range restrictions
rateLimit	Maximum requests per time window
mfa	Require multi-factor authentication confirmation
approval	Require approval from a designated approver

Example Request

curl -X POST https://app.veraid.io/api/v1/policies \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline - Scoped Deploy Access",
    "description": "Allow CI/CD identities to deploy only to staging and production, restricted to office IP ranges",
    "priority": 50,
    "effect": "ALLOW",
    "subjects": [
      { "type": "type", "value": "CI_CD" },
      { "type": "tag", "value": "deploy-authorized" }
    ],
    "resources": [
      { "type": "path", "value": "deploy/staging/*" },
      { "type": "path", "value": "deploy/production/*" }
    ],
    "actions": ["execute", "read"],
    "conditions": [
      {
        "type": "ip",
        "operator": "in",
        "value": ["10.0.0.0/8", "172.16.0.0/12", "203.0.113.0/24"]
      },
      {
        "type": "rateLimit",
        "operator": "max",
        "value": {
          "requests": 10,
          "window": "1h"
        }
      }
    ]
  }'

Example Response

{
  "id": "pol_def456",
  "name": "CI/CD Pipeline - Scoped Deploy Access",
  "description": "Allow CI/CD identities to deploy only to staging and production, restricted to office IP ranges",
  "priority": 50,
  "effect": "ALLOW",
  "subjects": [
    { "type": "type", "value": "CI_CD" },
    { "type": "tag", "value": "deploy-authorized" }
  ],
  "resources": [
    { "type": "path", "value": "deploy/staging/*" },
    { "type": "path", "value": "deploy/production/*" }
  ],
  "actions": ["execute", "read"],
  "conditions": [
    {
      "type": "ip",
      "operator": "in",
      "value": ["10.0.0.0/8", "172.16.0.0/12", "203.0.113.0/24"]
    },
    {
      "type": "rateLimit",
      "operator": "max",
      "value": {
        "requests": 10,
        "window": "1h"
      }
    }
  ],
  "active": true,
  "createdAt": "2026-03-19T10:00:00Z",
  "updatedAt": "2026-03-19T10:00:00Z"
}

---

Get Policy

Retrieve a single policy by ID.

GET /api/v1/policies/{id}

Example Request

curl -X GET https://app.veraid.io/api/v1/policies/pol_abc123 \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "id": "pol_abc123",
  "name": "Production Secrets - Business Hours Only",
  "description": "Restrict production secret access to business hours for non-emergency identities",
  "priority": 10,
  "effect": "DENY",
  "subjects": [
    { "type": "tag", "value": "non-emergency" }
  ],
  "resources": [
    { "type": "path", "value": "secrets/production/*" }
  ],
  "actions": ["read", "list"],
  "conditions": [
    {
      "type": "time",
      "operator": "outside",
      "value": {
        "start": "08:00",
        "end": "18:00",
        "timezone": "America/New_York",
        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"]
      }
    }
  ],
  "active": true,
  "evaluationCount": 4521,
  "lastEvaluatedAt": "2026-03-19T09:30:00Z",
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-03-01T14:30:00Z"
}

---

Update Policy

Update an existing policy. Only the fields provided in the request body are updated.

PUT /api/v1/policies/{id}

Example Request

curl -X PUT https://app.veraid.io/api/v1/policies/pol_abc123 \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated: Restrict production secret access to business hours (ET) for non-emergency identities",
    "conditions": [
      {
        "type": "time",
        "operator": "outside",
        "value": {
          "start": "07:00",
          "end": "19:00",
          "timezone": "America/New_York",
          "days": ["monday", "tuesday", "wednesday", "thursday", "friday"]
        }
      }
    ]
  }'

Example Response

{
  "id": "pol_abc123",
  "name": "Production Secrets - Business Hours Only",
  "description": "Updated: Restrict production secret access to business hours (ET) for non-emergency identities",
  "priority": 10,
  "effect": "DENY",
  "subjects": [
    { "type": "tag", "value": "non-emergency" }
  ],
  "resources": [
    { "type": "path", "value": "secrets/production/*" }
  ],
  "actions": ["read", "list"],
  "conditions": [
    {
      "type": "time",
      "operator": "outside",
      "value": {
        "start": "07:00",
        "end": "19:00",
        "timezone": "America/New_York",
        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"]
      }
    }
  ],
  "active": true,
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-03-19T10:15:00Z"
}

---

Delete Policy

Delete a policy. The policy is immediately deactivated and removed.

DELETE /api/v1/policies/{id}

Example Request

curl -X DELETE https://app.veraid.io/api/v1/policies/pol_abc123 \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "message": "Policy deleted successfully",
  "id": "pol_abc123"
}

Caution

Deleting a policy takes effect immediately. Any access that was governed by this policy will no longer be restricted (for DENY policies) or permitted (for ALLOW policies). Review the policy’s evaluation history before deletion to understand its impact.

---

Evaluate Policy

Evaluate access policies in real time for a given identity, resource, and action. This is useful for pre-flight checks before performing an operation or for building custom authorization logic.

POST /api/v1/policies/evaluate

Request Body

Field	Type	Required	Description
identityId	string	Yes	The identity requesting access
resource	string	Yes	The resource being accessed (e.g., secrets/production/db-url)
action	string	Yes	The action being performed (e.g., read, write, execute)
context	object	No	Additional context for condition evaluation (IP, timestamp, etc.)

Example Request

curl -X POST https://app.veraid.io/api/v1/policies/evaluate \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "identityId": "id_xyz789",
    "resource": "secrets/production/db-url",
    "action": "read",
    "context": {
      "ipAddress": "10.0.1.50",
      "timestamp": "2026-03-19T14:30:00Z",
      "userAgent": "veraid-sdk/1.2.0"
    }
  }'

Example Response (Allowed)

{
  "allowed": true,
  "matchedPolicies": [
    {
      "id": "pol_def456",
      "name": "CI/CD Pipeline - Scoped Deploy Access",
      "effect": "ALLOW",
      "priority": 50
    }
  ],
  "reason": "Access granted by policy 'CI/CD Pipeline - Scoped Deploy Access' (priority 50)"
}

Example Response (Denied)

{
  "allowed": false,
  "matchedPolicies": [
    {
      "id": "pol_abc123",
      "name": "Production Secrets - Business Hours Only",
      "effect": "DENY",
      "priority": 10
    }
  ],
  "reason": "Access denied by policy 'Production Secrets - Business Hours Only': request time 22:30 is outside allowed hours 07:00-19:00 ET"
}

Note

Policy evaluation is performed in priority order (lower number = higher priority). When multiple policies match, DENY policies take precedence over ALLOW policies at the same priority level. If no policies match, access is denied by default.