API Reference

Policies API

Programmatically manage database security policies. Create, update, test, and monitor policy violations through the API.

Endpoints

MethodEndpointDescriptionScope
GET/v1/policiesList all policiesread:policies
GET/v1/policies/{id}Get a specific policyread:policies
POST/v1/policiesCreate a new policywrite:policies
PUT/v1/policies/{id}Update an existing policywrite:policies
DELETE/v1/policies/{id}Delete a policywrite:policies
POST/v1/policies/{id}/enableEnable a policywrite:policies
POST/v1/policies/{id}/disableDisable a policywrite:policies
POST/v1/policies/{id}/testTest a policy in simulation modewrite:policies
GET/v1/policies/{id}/violationsGet policy violationsread:policies

Policy Types

DB Audit supports four types of security policies, each designed for different security use cases:

access_control

Control who can access databases and when

data_protection

Mask or redact sensitive data in query results

query_control

Block or restrict specific query patterns

alerting

Define conditions that trigger security alerts

Learn More

For detailed information on configuring each policy type, see the Security Policies documentation.

GET/v1/policies

List Policies

Retrieve a list of all security policies in your organization. Use query parameters to filter results.

Query Parameters

ParameterTypeDescription
typestringFilter by policy type (access_control, data_protection, query_control, alerting)
enabledbooleanFilter by enabled status
database_idstringFilter policies applied to a specific database
pageintegerPage number for pagination (default: 1)
per_pageintegerResults per page (default: 20, max: 100)

Example Request

# List all policies
curl -X GET "https://api.dbaudit.ai/v1/policies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Response
{
  "data": [
    {
      "id": "pol_abc123",
      "name": "restrict-admin-access",
      "type": "access_control",
      "enabled": true,
      "description": "Restrict admin access to business hours",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z",
      "databases": ["db_prod_01", "db_prod_02"],
      "violation_count": 42
    },
    {
      "id": "pol_def456",
      "name": "mask-pii-data",
      "type": "data_protection",
      "enabled": true,
      "description": "Mask personally identifiable information",
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-10T08:00:00Z",
      "databases": ["db_prod_01"],
      "violation_count": 0
    }
  ],
  "pagination": {
    "total": 15,
    "page": 1,
    "per_page": 20,
    "has_more": false
  }
}

Filtering Examples

# Filter policies by type and status
curl -X GET "https://api.dbaudit.ai/v1/policies?type=access_control&enabled=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter policies by database
curl -X GET "https://api.dbaudit.ai/v1/policies?database_id=db_prod_01" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/v1/policies/{id}

Get Policy

Retrieve detailed information about a specific policy, including its full configuration.

Example Request

# Get a specific policy
curl -X GET "https://api.dbaudit.ai/v1/policies/pol_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "id": "pol_abc123",
  "name": "restrict-admin-access",
  "type": "access_control",
  "enabled": true,
  "description": "Restrict admin access to business hours from trusted IPs",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z",
  "databases": ["db_prod_01", "db_prod_02"],
  "config": {
    "conditions": {
      "users": ["admin", "root", "postgres"],
      "time_window": {
        "start": "08:00",
        "end": "18:00",
        "timezone": "UTC",
        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"]
      },
      "allowed_ips": ["10.0.0.0/8", "192.168.1.0/24"]
    },
    "actions": [
      {
        "type": "block"
      },
      {
        "type": "alert",
        "severity": "critical",
        "channels": ["slack", "pagerduty"]
      }
    ]
  },
  "violation_count": 42,
  "last_violation_at": "2024-01-19T23:15:00Z"
}
POST/v1/policies

Create Policy

Create a new security policy. The policy configuration varies based on the policy type.

Request Body

namerequiredUnique name for the policy
typerequiredPolicy type (access_control, data_protection, query_control, alerting)
databasesrequiredArray of database IDs to apply the policy to
configrequiredPolicy-specific configuration object
descriptionoptionalHuman-readable description
enabledoptionalWhether to enable the policy immediately (default: false)

Example Request

# Create a new policy
curl -X POST "https://api.dbaudit.ai/v1/policies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "block-destructive-queries",
    "type": "query_control",
    "description": "Block DROP and TRUNCATE statements in production",
    "databases": ["db_prod_01", "db_prod_02"],
    "enabled": true,
    "config": {
      "rules": [
        {
          "name": "block-drop",
          "pattern": "DROP\\s+(TABLE|DATABASE|INDEX)",
          "action": "block",
          "severity": "critical",
          "message": "DROP statements are not allowed in production"
        },
        {
          "name": "block-truncate",
          "pattern": "TRUNCATE\\s+TABLE",
          "action": "block",
          "severity": "critical",
          "message": "TRUNCATE statements are not allowed in production"
        }
      ],
      "exceptions": {
        "users": ["migration_user"],
        "applications": ["schema_manager"]
      }
    }
  }'

# Response
{
  "id": "pol_ghi789",
  "name": "block-destructive-queries",
  "type": "query_control",
  "enabled": true,
  "description": "Block DROP and TRUNCATE statements in production",
  "created_at": "2024-01-21T09:00:00Z",
  "updated_at": "2024-01-21T09:00:00Z",
  "databases": ["db_prod_01", "db_prod_02"],
  "config": { ... }
}
PUT/v1/policies/{id}

Update Policy

Update an existing policy. Only provided fields will be updated; omitted fields remain unchanged.

Example Request

# Update a policy
curl -X PUT "https://api.dbaudit.ai/v1/policies/pol_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "config": {
      "conditions": {
        "users": ["admin", "root", "postgres", "dba"],
        "time_window": {
          "start": "07:00",
          "end": "19:00",
          "timezone": "UTC",
          "days": ["monday", "tuesday", "wednesday", "thursday", "friday"]
        },
        "allowed_ips": ["10.0.0.0/8", "192.168.1.0/24", "172.16.0.0/12"]
      }
    }
  }'
DELETE/v1/policies/{id}

Delete Policy

Permanently delete a policy. This action cannot be undone. Historical violation data is retained.

Destructive Action

Consider disabling the policy instead of deleting it if you may need it again in the future.

Example Request

# Delete a policy
curl -X DELETE "https://api.dbaudit.ai/v1/policies/pol_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "deleted": true,
  "id": "pol_abc123"
}
POST/v1/policies/{id}/enable/disable

Enable/Disable Policy

Toggle a policy on or off without deleting it. Disabled policies are not enforced but retain their configuration.

Example Request

# Enable a policy
curl -X POST "https://api.dbaudit.ai/v1/policies/pol_abc123/enable" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Disable a policy
curl -X POST "https://api.dbaudit.ai/v1/policies/pol_abc123/disable" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "id": "pol_abc123",
  "enabled": true,
  "updated_at": "2024-01-21T10:00:00Z"
}
POST/v1/policies/{id}/test

Test Policy

Test a policy against simulated input without enforcing it. Useful for validating policy configuration before enabling.

Safe Testing

This endpoint only simulates policy evaluation. No queries are blocked and no alerts are sent.

Example Request

# Test a policy in simulation mode
curl -X POST "https://api.dbaudit.ai/v1/policies/pol_abc123/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM users WHERE id = 1",
    "user": "admin",
    "source_ip": "203.0.113.50",
    "timestamp": "2024-01-21T22:30:00Z"
  }'

# Response
{
  "would_trigger": true,
  "matched_conditions": [
    {
      "type": "time_window",
      "reason": "Access outside allowed hours (08:00-18:00 UTC)"
    },
    {
      "type": "ip_restriction",
      "reason": "IP 203.0.113.50 not in allowed ranges"
    }
  ],
  "actions_would_execute": [
    {"type": "block"},
    {"type": "alert", "severity": "critical"}
  ]
}
GET/v1/policies/{id}/violations

Get Policy Violations

Retrieve a list of policy violations. Filter by time range, severity, or user.

Example Request

# Get policy violations
curl -X GET "https://api.dbaudit.ai/v1/policies/pol_abc123/violations?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "vio_xyz123",
      "policy_id": "pol_abc123",
      "timestamp": "2024-01-19T23:15:00Z",
      "user": "admin",
      "database": "db_prod_01",
      "source_ip": "203.0.113.50",
      "query": "SELECT * FROM users",
      "matched_conditions": ["time_window", "ip_restriction"],
      "action_taken": "blocked",
      "severity": "critical"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "per_page": 10,
    "has_more": true
  }
}

SDK Examples

Use our official SDKs to interact with the Policies API in your preferred language.

Python

import dbaudit

client = dbaudit.Client()

# List all policies
policies = client.policies.list()

# Get a specific policy
policy = client.policies.get("pol_abc123")

# Create a new policy
new_policy = client.policies.create(
    name="block-after-hours",
    type="access_control",
    databases=["db_prod_01"],
    config={
        "conditions": {
            "time_window": {
                "start": "08:00",
                "end": "18:00"
            }
        },
        "actions": [{"type": "block"}]
    }
)

# Enable/disable
client.policies.enable("pol_abc123")
client.policies.disable("pol_abc123")

# Test a policy
result = client.policies.test("pol_abc123", {
    "query": "SELECT * FROM users",
    "user": "admin",
    "source_ip": "203.0.113.50"
})

# Get violations
violations = client.policies.violations("pol_abc123", limit=100)

Node.js

import { DBaudit } from '@dbaudit/sdk';

const client = new DBaudit();

// List all policies
const policies = await client.policies.list();

// Get a specific policy
const policy = await client.policies.get('pol_abc123');

// Create a new policy
const newPolicy = await client.policies.create({
  name: 'block-after-hours',
  type: 'access_control',
  databases: ['db_prod_01'],
  config: {
    conditions: {
      time_window: {
        start: '08:00',
        end: '18:00'
      }
    },
    actions: [{ type: 'block' }]
  }
});

// Enable/disable
await client.policies.enable('pol_abc123');
await client.policies.disable('pol_abc123');

// Test a policy
const result = await client.policies.test('pol_abc123', {
  query: 'SELECT * FROM users',
  user: 'admin',
  sourceIp: '203.0.113.50'
});

// Get violations
const violations = await client.policies.violations('pol_abc123', { limit: 100 });

Error Responses

The Policies API returns standard HTTP status codes and error messages:

400

Bad Request

Invalid policy configuration or missing required fields.

401

Unauthorized

Missing or invalid authentication credentials.

403

Forbidden

Insufficient permissions. Requires read:policies or write:policies scope.

404

Not Found

Policy with the specified ID does not exist.

409

Conflict

A policy with the same name already exists.

422

Unprocessable Entity

Policy configuration is invalid for the specified type.

Related Resources

Explore more API endpoints and learn how to use policies effectively:

API Authentication
Events API
Security Policies Guide

Ready to Automate Policy Management?

Start using the Policies API to programmatically manage your database security policies.

Get Your API KeyContact Sales