AI Policy

The AI Policy APIs enable you to create, manage, and enforce governance policies for AI operations across your organization. These policies help ensure compliance, security, and responsible AI usage at organization, workspace, or repository levels.

Overview

AI Policies are flexible governance rules that can be applied at different organizational levels to control and monitor AI usage. They provide a powerful framework for:

Compliance Enforcement: Ensure AI operations comply with regulatory requirements
Security Control: Prevent sensitive data leakage through AI interactions
Content Moderation: Define acceptable use policies for AI services
Risk Management: Classify and respond to different risk levels
Audit Trail: Track policy violations and enforcement actions

Policy Scope Hierarchy

Policies can be created at three levels, forming an inheritance hierarchy:

Organization-Level: Applies to all workspaces and repositories in the organization
Workspace-Level: Applies to all repositories within a specific workspace
Repository-Level: Applies only to a specific repository

Lower-level policies can supplement (but not override) higher-level policies.

Policy Components

Risk Types

Classify policies based on their risk level:

LOW - Informational policies, minimal impact if violated
MEDIUM - Important policies with moderate business impact
HIGH - Critical policies requiring immediate attention

Action Types

Define what happens when a policy is violated:

Action Type

Value

Behavior

Log Only

Record the violation for audit purposes

Alert

Log violation and send notifications to administrators

Block

Prevent the action from completing and alert administrators

Policy Content

Policy content is defined in natural language and describes:

What actions are prohibited or required
Context and rationale for the policy
Specific examples of violations
Any exceptions or special cases

Example Policy Contents:

"Do not allow sharing of personally identifiable information (PII) such as 
social security numbers, credit card numbers, or personal addresses in AI 
interactions."

"All API requests must include proper authentication. Do not allow anonymous 
or unauthenticated access to AI services."

"Prevent disclosure of proprietary source code, internal system architecture, 
or confidential business information through AI conversations."

Available Endpoints

Method

API Reference

Description

POST/policy

post__policy

Create a new AI policy.

PUT/policy/{policyId}

put__policy_{policyId}

Update an existing policy.

GET/policy

get__policy

List policies with optional filtering.

GET/policy/{policyId}

get__policy_{policyId}

Get detailed information about a specific policy.

GET/policy/violations

get__policy_violations

Retrieve a list of policy violations that have occurred during AI operations.

GET/policy/{policyId}/violations

get__policy_{policyId}_violations

Retrieve all violations for a specific policy.

GET/policy/alerts

get__policy_alerts

Retrieve all policy alerts across your organization with optional filtering.

GET/policy/{policyId}/alerts

get__policy_{policyId}_alerts

Retrieve all alerts for a specific policy.

DELETE/policy/{policyId}

delete__policy_{policyId}

Permanently delete an AI governance policy.

Common Use Cases

1. Creating an Organization-Level Policy

// Create a high-risk policy that blocks PII sharing across the entire organization
const response = await client.createPolicy({
  name: "PII Protection Policy",
  content: "Do not allow sharing of personally identifiable information (PII) such as social security numbers, credit card numbers, or personal addresses in AI interactions.",
  riskType: "HIGH",
  actionType: 2, // Block
  orgId: "org-123",
  workspaceId: null, // Null = org-level
  repoId: null
});

console.log(`Created policy: ${response.policy.id}`);

2. Creating a Workspace-Level Policy

// Create a medium-risk policy for a specific workspace
const response = await client.createPolicy({
  name: "Development Data Policy",
  content: "Do not use production data in development AI interactions. Always use anonymized or synthetic data for testing.",
  riskType: "MEDIUM",
  actionType: 1, // Alert
  orgId: "org-123",
  workspaceId: "workspace-dev",
  repoId: null
});

3. Creating a Repository-Specific Policy

// Create a repository-specific policy
const response = await client.createPolicy({
  name: "Customer Support Bot Policy",
  content: "Only provide information from approved documentation. Do not speculate or provide unverified information.",
  riskType: "MEDIUM",
  actionType: 1, // Alert
  orgId: "org-123",
  workspaceId: "workspace-support",
  repoId: "repo-support-bot"
});

4. Listing Policies

// Get all organization policies
const orgPolicies = await client.getPolicies({
  orgId: "org-123"
});

// Get workspace-specific policies
const workspacePolicies = await client.getPolicies({
  orgId: "org-123",
  workspaceId: "workspace-456"
});

// Get repository-specific policies
const repoPolicies = await client.getPolicies({
  orgId: "org-123",
  workspaceId: "workspace-456",
  repoId: "repo-789"
});

// Display policies
orgPolicies.policies.forEach(policy => {
  console.log(`${policy.name} (${policy.riskType})`);
  console.log(`  Action: ${policy.actionType === 2 ? 'Block' : policy.actionType === 1 ? 'Alert' : 'Log'}`);
  console.log(`  Scope: ${policy.repoId ? 'Repository' : policy.workspaceId ? 'Workspace' : 'Organization'}`);
});

5. Updating a Policy

// Update policy to increase severity
await client.updatePolicy("policy-123", {
  riskType: "HIGH",
  actionType: 2 // Change from alert to block
});

// Update policy content
await client.updatePolicy("policy-123", {
  content: "Enhanced policy description with additional examples and clarifications."
});

6. Deleting a Policy

// Delete an obsolete policy
await client.deletePolicy("policy-123");
console.log("Policy deleted successfully");

Policy Design Best Practices

1. Clear and Specific Content

Good:

"Do not share customer email addresses, phone numbers, or physical addresses 
in AI conversations. This includes partial information that could be used to 
identify individuals."

Avoid:

"Don't share personal info."

2. Appropriate Risk Classification

HIGH: Data breaches, regulatory violations, security threats
MEDIUM: Business process violations, quality issues
LOW: Best practice recommendations, style guidelines

3. Balanced Action Types

Use Block (2) sparingly for critical security policies
Use Alert (1) for important policies that need review
Use Log (0) for informational policies and monitoring

4. Layered Policy Strategy

// Layer 1: Organization-level baseline
await client.createPolicy({
  name: "Baseline Security Policy",
  content: "Never share passwords, API keys, or authentication tokens.",
  riskType: "HIGH",
  actionType: 2,
  orgId: "org-123",
  workspaceId: null,
  repoId: null
});

// Layer 2: Workspace-specific policies
await client.createPolicy({
  name: "Healthcare Compliance",
  content: "Comply with HIPAA regulations. Never share patient health information.",
  riskType: "HIGH",
  actionType: 2,
  orgId: "org-123",
  workspaceId: "workspace-healthcare",
  repoId: null
});

// Layer 3: Repository-specific policies
await client.createPolicy({
  name: "Patient Portal Guidelines",
  content: "Only provide general health information. Direct specific medical questions to healthcare providers.",
  riskType: "MEDIUM",
  actionType: 1,
  orgId: "org-123",
  workspaceId: "workspace-healthcare",
  repoId: "repo-patient-portal"
});

Permission Model

Policy operations require different permission levels based on scope:

Organization-Level Policies

Create: Organization owner or administrator
Read: All organization members can read org-level policies
Update/Delete: Organization owner or administrator

Workspace-Level Policies

Create: Organization administrators or workspace administrators
Read: Workspace members can read workspace policies
Update/Delete: Organization administrators or workspace administrators

Repository-Level Policies

Create: Users with repository access
Read: Users with repository access
Update/Delete: Users with repository write access

Audit and Compliance

All policy operations maintain a complete audit trail:

Creator Information

Each policy tracks:

User who created it
Creation timestamp
Original policy configuration

Update Tracking

Each update records:

User who made the change
Update timestamp
Changed fields

Example Audit Information

const policy = await client.getPolicy("policy-123");

console.log("Created by:", policy.policy.createdBy.email);
console.log("Created at:", policy.policy.createdAt);
console.log("Last updated by:", policy.policy.lastUpdatedBy.email);
console.log("Last updated at:", policy.policy.lastUpdatedAt);

Policy Enforcement

Policies are enforced in real-time during AI operations:

Request Evaluation: When an AI operation occurs, all applicable policies are evaluated
Policy Matching: Policies are matched based on hierarchy (org → workspace → repo)
Action Execution: Based on policy actionType:
- Log (0): Violation is recorded
- Alert (1): Violation is recorded and administrators are notified
- Block (2): Operation is prevented and administrators are notified

Error Handling

Common error scenarios when working with policies:

400 Bad Request

Causes:

Missing required fields
Invalid repoId/workspaceId combination
No fields provided for update

try {
  await client.createPolicy(policyData);
} catch (error) {
  if (error.status === 400) {
    console.error("Validation error:", error.message);
  }
}

403 Forbidden

Causes:

User doesn't belong to the organization
Insufficient permissions for policy scope level
Attempting to modify policy user doesn't have access to

try {
  await client.updatePolicy("policy-123", updates);
} catch (error) {
  if (error.status === 403) {
    console.error("Permission denied:", error.message);
  }
}

404 Not Found

Causes:

Policy doesn't exist
Policy has been deleted

try {
  await client.getPolicy("invalid-policy-id");
} catch (error) {
  if (error.status === 404) {
    console.error("Policy not found");
  }
}

TypeScript Client Library

The Flashback TypeScript client provides convenient methods for all policy operations:

import { FlashbackClient } from '@flashbacktech/flashbackclient';

const client = new FlashbackClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://backend.flashback.tech'
});

// Create policy
const created = await client.createPolicy({
  name: "My Policy",
  content: "Policy content...",
  riskType: "HIGH",
  actionType: 2,
  orgId: "org-123",
  workspaceId: null,
  repoId: null
});

// List policies
const policies = await client.getPolicies({
  orgId: "org-123",
  workspaceId: "workspace-456"
});

// Get single policy
const policy = await client.getPolicy("policy-id");

// Update policy
await client.updatePolicy("policy-id", {
  name: "Updated Name",
  riskType: "MEDIUM"
});

// Delete policy
await client.deletePolicy("policy-id");

Integration Examples

Setting Up a Comprehensive Policy Framework

class PolicyManager {
  constructor(private client: FlashbackClient, private orgId: string) {}

  async setupBaselinePolicies() {
    // Security policies
    await this.createSecurityPolicies();
    
    // Compliance policies
    await this.createCompliancePolicies();
    
    // Quality policies
    await this.createQualityPolicies();
  }

  private async createSecurityPolicies() {
    // PII Protection
    await this.client.createPolicy({
      name: "PII Protection",
      content: "Never share personally identifiable information...",
      riskType: "HIGH",
      actionType: 2,
      orgId: this.orgId,
      workspaceId: null,
      repoId: null
    });

    // Credential Security
    await this.client.createPolicy({
      name: "Credential Security",
      content: "Never share passwords, API keys, tokens, or secrets...",
      riskType: "HIGH",
      actionType: 2,
      orgId: this.orgId,
      workspaceId: null,
      repoId: null
    });
  }

  private async createCompliancePolicies() {
    // Add compliance-specific policies
  }

  private async createQualityPolicies() {
    // Add quality-related policies
  }
}

// Usage
const manager = new PolicyManager(client, "org-123");
await manager.setupBaselinePolicies();

Best Practices Summary

Start with Organization-Level: Create baseline security and compliance policies at org level
Be Specific: Write clear, specific policy content with examples
Use Appropriate Actions: Reserve blocking for critical policies
Layer Policies: Use hierarchy to create comprehensive coverage
Review Regularly: Audit and update policies as requirements change
Test Policies: Verify policies work as expected before wide deployment
Document Intent: Include rationale in policy content
Monitor Violations: Regularly review policy violations (see Violations APIs)

AI LLM Management APIs - Configure AI provider connections
AI API Keys - Manage repository-specific API keys for AI operations
Policy Violations - Monitor and analyze policy violations

Next Steps

Design your policy framework based on organizational requirements
Create organization-level baseline policies
Add workspace-specific policies for different teams or projects
Create repository-specific policies for specialized use cases
Monitor policy violations and adjust as needed
Regularly review and update policies to maintain effectiveness

Previouspost__ai_llm_{aillmId}_validate Nextpost__policy

Last updated 6 hours ago

Was this helpful?

hashtagOverview

hashtagPolicy Scope Hierarchy

hashtagPolicy Components

hashtagRisk Types

hashtagAction Types

hashtagPolicy Content

hashtagAvailable Endpoints

hashtagCommon Use Cases

hashtag1. Creating an Organization-Level Policy

hashtag2. Creating a Workspace-Level Policy

hashtag3. Creating a Repository-Specific Policy

hashtag4. Listing Policies

hashtag5. Updating a Policy

hashtag6. Deleting a Policy

hashtagPolicy Design Best Practices

hashtag1. Clear and Specific Content

hashtag2. Appropriate Risk Classification

hashtag3. Balanced Action Types

hashtag4. Layered Policy Strategy

hashtagPermission Model

hashtagOrganization-Level Policies

hashtagWorkspace-Level Policies

hashtagRepository-Level Policies

hashtagAudit and Compliance

hashtagCreator Information

hashtagUpdate Tracking

hashtagExample Audit Information

hashtagPolicy Enforcement

hashtagError Handling

hashtag400 Bad Request

hashtag403 Forbidden

hashtag404 Not Found

hashtagTypeScript Client Library

hashtagIntegration Examples

hashtagSetting Up a Comprehensive Policy Framework

hashtagBest Practices Summary

hashtagRelated Documentation

hashtagNext Steps

Overview

Policy Scope Hierarchy

Policy Components

Risk Types

Action Types

Policy Content

Available Endpoints

Common Use Cases

1. Creating an Organization-Level Policy

2. Creating a Workspace-Level Policy

3. Creating a Repository-Specific Policy

4. Listing Policies

5. Updating a Policy

6. Deleting a Policy

Policy Design Best Practices

1. Clear and Specific Content

2. Appropriate Risk Classification

3. Balanced Action Types

4. Layered Policy Strategy

Permission Model

Organization-Level Policies

Workspace-Level Policies

Repository-Level Policies

Audit and Compliance

Creator Information

Update Tracking

Example Audit Information

Policy Enforcement

Error Handling

400 Bad Request

403 Forbidden

404 Not Found

TypeScript Client Library

Integration Examples

Setting Up a Comprehensive Policy Framework

Best Practices Summary

Related Documentation

Next Steps