API Reference

Policies API

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

Endpoints

Method Endpoint Description Scope
GET /v1/policies List all policies read:policies
GET /v1/policies/{id} Get a specific policy read:policies
POST /v1/policies Create a new policy write:policies
PUT /v1/policies/{id} Update an existing policy write:policies
DELETE /v1/policies/{id} Delete a policy write:policies
POST /v1/policies/{id}/enable Enable a policy write:policies
POST /v1/policies/{id}/disable Disable a policy write:policies
POST /v1/policies/{id}/test Test a policy in simulation mode write:policies
GET /v1/policies/{id}/violations Get policy violations read: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

Parameter Type Description
type string Filter by policy type (access_control, data_protection, query_control, alerting)
enabled boolean Filter by enabled status
database_id string Filter policies applied to a specific database
page integer Page number for pagination (default: 1)
per_page integer Results 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

name required Unique name for the policy
type required Policy type (access_control, data_protection, query_control, alerting)
databases required Array of database IDs to apply the policy to
config required Policy-specific configuration object
description optional Human-readable description
enabled optional Whether 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 Key Contact Sales