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:

1. Organization-Level: Applies to all workspaces and repositories in the organization

2. Workspace-Level: Applies to all repositories within a specific workspace

3. 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	0	Record the violation for audit purposes
Alert	1	Log violation and send notifications to administrators
Block	2	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."

AI Policy API Calls

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:

1. Request Evaluation: When an AI operation occurs, all applicable policies are evaluated

2. Policy Matching: Policies are matched based on hierarchy (org → workspace → repo)

3. 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

1. Start with Organization-Level: Create baseline security and compliance policies at org level

2. Be Specific: Write clear, specific policy content with examples

3. Use Appropriate Actions: Reserve blocking for critical policies

4. Layer Policies: Use hierarchy to create comprehensive coverage

5. Review Regularly: Audit and update policies as requirements change

6. Test Policies: Verify policies work as expected before wide deployment

7. Document Intent: Include rationale in policy content

8. Monitor Violations: Regularly review policy violations (see Violations APIs)

Related Documentation

• 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

1. Design your policy framework based on organizational requirements

2. Create organization-level baseline policies

3. Add workspace-specific policies for different teams or projects

4. Create repository-specific policies for specialized use cases

5. Monitor policy violations and adjust as needed

6. Regularly review and update policies to maintain effectiveness