Skip to content

Component Policies

Policies provide a declarative way to enforce security and access control rules on your components. Instead of writing custom logic for every access control scenario, you define policies that the platform automatically evaluates and enforces.

Overview

Each component can have one or more policies configured in its settings. Policies are evaluated based on their type and priority, and they control who can access specific fields or data within the component.

Key characteristics:

  • Policies are defined per component version
  • Multiple policies can coexist and are evaluated in priority order (highest first)
  • Policies can be enabled or disabled without removing them
  • Admin users bypass all policy checks

Policy Structure

A policy is defined with the following properties:

Property Type Required Description
type string Yes The policy type. Currently supported: field_access
name string Yes Human-readable name for the policy
description string No Optional explanation of what the policy does
enabled boolean Yes Whether the policy is currently active
priority number No Higher priority wins in case of conflicts (default: 0)
config object Yes Type-specific configuration object

Example

{
  "type": "field_access",
  "name": "Restrict Salary Field",
  "description": "Only HR managers can read or update the salary field",
  "enabled": true,
  "priority": 10,
  "config": {
    "fields": ["salary", "bonus"],
    "actions": ["read", "update"],
    "roles": ["role-uuid-hr-manager", "role-uuid-admin"]
  }
}

Note: The roles array contains role UUIDs, not human-readable names.

Policy Types

field_access

Controls which user roles can read or update specific fields on the component.

Config properties:

Property Type Description
fields string[] List of field keys this policy applies to
actions string[] Allowed actions: read, update
roles string[] Roles that are granted access to the specified fields

How it works:

When a user reads or updates a field, the platform checks all enabled field_access policies in priority order (highest first). The first matching policy that covers the field, the action, and a role the user holds determines access. If no policies are defined for a field, all roles can access it freely.

Example — Restrict sensitive fields:

{
  "type": "field_access",
  "name": "Financial Data Access",
  "enabled": true,
  "priority": 10,
  "config": {
    "fields": ["salary", "bank_account", "tax_id"],
    "actions": ["read", "update"],
    "roles": ["role-uuid-finance-team", "role-uuid-hr-manager"]
  }
}

Example — Read-only fields for specific roles:

{
  "type": "field_access",
  "name": "Allow View Only",
  "enabled": true,
  "priority": 5,
  "config": {
    "fields": ["salary"],
    "actions": ["read"],
    "roles": ["role-uuid-team-lead"]
  }
}

In this setup, a user with the role-uuid-team-lead role can view the salary field but cannot update it.

data_access (coming soon)

Controls access to data records based on custom filtering rules. Use this to restrict which records users can see or modify based on their role.

Info

data_access policies are not yet supported. This section is reserved for future implementation.

limits (coming soon)

Defines operational limits for the component, such as maximum number of records or rate limits for specific operations.

Info

limits policies are not yet supported. This section is reserved for future implementation.

Priority System

When multiple policies of the same type exist, they are evaluated in descending priority order (highest priority first). The first policy that matches the user's role and the requested action determines the outcome.

This allows you to create layered access control:

[
  {
    "type": "field_access",
    "name": "Full Access for Admins",
    "enabled": true,
    "priority": 100,
    "config": {
      "fields": ["*"],
      "actions": ["read", "update"],
      "roles": ["role-uuid-admin"]
    }
  },
  {
    "type": "field_access",
    "name": "Read-only for Support",
    "enabled": true,
    "priority": 50,
    "config": {
      "fields": ["email", "name", "status"],
      "actions": ["read"],
      "roles": ["role-uuid-support"]
    }
  }
]

Managing Policies

Policies have dedicated API endpoints and SDK methods for installation, updates, and deletion. This provides better control and validation compared to modifying the entire settings object.

API Endpoints

Get a Policy

GET /v4/system/component/{ref}/{version}/policies/{name}

Retrieves a single policy by name from the specified component version.

URL Parameters:

  • {ref} — Component reference (e.g., namespace::component-name)
  • {version} — Component version (e.g., 0.1.0)
  • {name} — Policy name

Response: 200 OK

{
  "type": "field_access",
  "name": "Restrict Salary Field",
  "description": "Only HR managers can access salary information",
  "enabled": true,
  "priority": 10,
  "config": {
    "fields": ["salary", "bonus"],
    "actions": ["read", "update"],
    "roles": ["role-uuid-hr-manager"]
  }
}

Error Responses:

  • 404 Not Found — Policy with the given name does not exist
  • 403 Forbidden — User lacks policies::read permission

Permissions Required: policies::read

Install a Policy

POST /v4/system/component/{ref}/{version}/policies

Request Body:

{
  "type": "field_access",
  "name": "Restrict Salary Field",
  "description": "Only HR managers can access salary information",
  "enabled": true,
  "priority": 10,
  "config": {
    "fields": ["salary", "bonus"],
    "actions": ["read", "update"],
    "roles": ["role-uuid-hr-manager"]
  }
}

Permissions Required: policies::create

Update a Policy

PATCH /v4/system/component/{ref}/{version}/policies/{name}

Request Body: (partial update supported)

{
  "enabled": false,
  "priority": 20
}

Permissions Required: policies::edit

Delete a Policy

DELETE /v4/system/component/{ref}/{version}/policies/{name}

Permissions Required: policies::delete

Using the SDK

The SDK provides dedicated methods for managing policies:

Get a Policy

const component = new Component("my_component")

const policy = await component.getPolicy('Restrict Salary Field', '0.1.0')
console.log(policy.data)

Install a Policy

const component = new Component("my_component")

await component.installPolicy({
  type: "field_access",
  name: "Restrict Salary Field",
  description: "Only HR managers can access salary information",
  enabled: true,
  priority: 10,
  config: {
    fields: ["salary", "bonus"],
    actions: ["read", "update"],
    roles: ["role-uuid-hr-manager"]
  }
}, '0.1.0')

Update a Policy

// Partial updates are supported
await component.updatePolicy('Restrict Salary Field', '0.1.0', {
  enabled: false,
  priority: 20
})

Delete a Policy

await component.deletePolicy('Restrict Salary Field', '0.1.0')

Viewing Policies

Policies are part of the component settings and can be retrieved using the standard settings endpoint:

const settings = await component.settings()
console.log(settings.policies)

Best Practices

  1. Start permissive, then restrict — If no policies are defined, all fields are accessible. Add policies only for fields that need protection.
  2. Use meaningful names — Policy names should clearly describe what they control (e.g., "Restrict Financial Data" instead of "Policy 1").
  3. Leverage priorities — Use higher priority values for broader access rules and lower priorities for restrictive ones.
  4. Keep policies enabled/disabled — Instead of deleting policies, disable them. This makes it easy to re-enable them later.
  5. Test with non-admin users — Admin users bypass all policy checks. Always test your policies with regular user roles.