Governance API

The Governance module provides fine-grained access control and compliance features including role-based access control (RBAC), user groups, destination policies, access policies, and deletion rules.

Endpoint Groups

Roles

Roles define sets of permissions that can be assigned to workspace members or groups. Zeotap includes three built-in system roles (owner, admin, member) and supports custom roles.

List Roles

GET /api/v1/workspaces/{id}/roles

[
  {
    "id": "00000000-0000-0000-0000-000000000001",
    "workspace_id": null,
    "name": "owner",
    "description": "Full access to all workspace resources",
    "is_system": true,
    "permissions": ["sources.read", "sources.write", "sources.delete", "..."],
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspace_id": "660e8400-e29b-41d4-a716-446655440000",
    "name": "data_analyst",
    "description": "Read-only access to models and audiences",
    "is_system": false,
    "permissions": ["sources.read", "models.read", "audiences.read"],
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Create Custom Role

POST /api/v1/workspaces/{id}/roles

Request Body

{
  "name": "data_analyst",
  "description": "Read-only access to models and audiences",
  "permissions": [
    "sources.read",
    "models.read",
    "audiences.read",
    "traits.read",
    "insights.read"
  ]
}

System Roles

Permissions

Permissions are granular access control strings organized by category.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "sources.read",
    "category": "sources",
    "description": "View sources and connection details",
    "created_at": "2024-01-01T00:00:00Z"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "key": "sources.write",
    "category": "sources",
    "description": "Create and update sources",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

Permission Categories

Groups

Groups organize workspace members and can be assigned a role that applies to all members.

Create Group

POST /api/v1/workspaces/{id}/groups

{
  "name": "Marketing Team",
  "description": "Marketing department members",
  "role_id": "550e8400-e29b-41d4-a716-446655440000"
}

Group Object

Members

Manage group membership.

Add Member

POST /api/v1/workspaces/{id}/groups/{groupId}/members

{
  "account_id": "770e8400-e29b-41d4-a716-446655440000"
}

Group Member Object

Destination Policies

Destination policies are sync-time governance policies that restrict which records can be sent to specific destination types. They act as guardrails to prevent sensitive data from reaching certain platforms. The API path remains destination-rules for backwards compatibility.

Create Destination Policy

POST /api/v1/workspaces/{id}/destination-rules

{
  "name": "GDPR - No EU Customers to Facebook",
  "description": "Prevent EU customer data from being synced to Facebook Ads",
  "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
  "destination_type": "facebook_ads",
  "filter_tree": {
    "type": "condition",
    "condition_type": "property",
    "column": "country",
    "operator": "not_in",
    "value": ["DE", "FR", "IT", "ES", "NL", "BE", "AT", "SE", "DK", "FI"]
  },
  "enabled": true
}

Destination Policy Object

Access Policies

Access Policies provide row-level access control by restricting which records a user or group can see. They use filter trees (same as audiences) to define visibility boundaries. The API path remains subsets for backwards compatibility.

Access Policy Categories

Categories organize access policies into logical groups (e.g., Region, Brand, Business Unit).

Access Policy Endpoints

Create Access Policy

{
  "name": "US Region",
  "description": "Only US customer records",
  "category_id": "550e8400-e29b-41d4-a716-446655440000",
  "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
  "filter_tree": {
    "type": "condition",
    "condition_type": "property",
    "column": "country",
    "operator": "equals",
    "value": "US"
  }
}

Access Policy Assignments

Assign access policies to groups to restrict their data visibility. Assignments are nested under each access policy.

Create Assignment

{
  "group_id": "aae8400-e29b-41d4-a716-446655440000"
}

Access Policy Object

Deletion Rules

Deletion rules erase warehouse data for an audience-scoped population, on demand or on a schedule, and record every run in an audit log. See Deletion Rules for the eligibility rules and safety controls.

Reads require deletion_rules.read, writes deletion_rules.write, and both run endpoints deletion_rules.execute.

Every endpoint additionally requires the workspace to have the Deletion Rules feature enabled by a platform administrator; otherwise they answer 403 deletion rules are not enabled for this workspace. See Availability.

Eligibility and safety refusals — an ineligible target, an empty filter, a column that cannot be cleared, a pinned join that has since drifted — answer 400 with the specific reason in error. Read it: it names the target and says what is wrong with it, which is the only place that information exists.

Create Deletion Rule

POST /api/v1/workspaces/{id}/deletion-rules

filter_tree is required and must carry at least one condition — a rule may not match every record by default. dry_run defaults to true and enabled to false, so omitting them creates an observe-only rule.

{
  "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
  "name": "Erase opted-out EU customers",
  "description": "Fulfils standing right-to-erasure requests for EU opt-outs.",
  "filter_tree": {
    "type": "and",
    "children": [
      {
        "type": "condition",
        "condition_type": "property",
        "field": "region",
        "operator": "equals",
        "value": "EU"
      },
      {
        "type": "condition",
        "condition_type": "property",
        "field": "erasure_requested",
        "operator": "equals",
        "value": true
      }
    ]
  },
  "targets": [
    { "model_id": "770e8400-e29b-41d4-a716-446655440000", "action": "delete_rows" },
    {
      "model_id": "881e8400-e29b-41d4-a716-446655440000",
      "action": "null_columns",
      "columns": ["shipping_address", "phone"]
    }
  ],
  "schedule": "0 3 * * *",
  "dry_run": true,
  "enabled": false
}

Deletion Rule Object

Deletion Target Object

Trigger a Run

POST /api/v1/workspaces/{id}/deletion-rules/{ruleId}/run POST /api/v1/workspaces/{id}/deletion-rules/{ruleId}/dry-run

Both return 202 Accepted with the opened run in running state — the deletion continues past the request, so poll the run log to follow it. /dry-run never mutates, whatever the rule’s own dry_run value. /run returns 400 when the rule is disabled.

Deletion Run Object

Deletion Run Target Object