Policy Management

Policies define the permissions and access control rules that govern user access to resources. A policy binds a role to a principal (user, group, or service account) on a specific resource.

Policy Structure

type Policy struct {
    ID            string
    RoleID        string         // Role being assigned
    ResourceID    string         // Target resource
    ResourceType  string         // Resource namespace
    PrincipalID   string         // User/group/service account
    PrincipalType string         // "app/user", "app/group", "app/serviceuser"
    Metadata      map[string]any
    CreatedAt     time.Time
    UpdatedAt     time.Time
}

How Policies Work

When a policy is created:

Policy Created

A policy record is stored in Frontier’s database with role, principal, and resource information

Role Binding in SpiceDB

Frontier creates a app/rolebinding object in SpiceDB with three key relations

Permission Graph Built

SpiceDB constructs a permission graph connecting the user to permissions via the role

Access Checks

When the user requests access, SpiceDB traverses the graph to verify permissions

SpiceDB Relations Created

For each policy, three relations are established:

Example: John as Organization Owner

// 1. Link user as bearer of the role
app/rolebinding:policy123#bearer@app/user:john

// 2. Link the role to the binding
app/rolebinding:policy123#role@app/role:app_organization_owner

// 3. Link the binding to the resource
app/organization:acme#granted@app/rolebinding:policy123

This creates a path: User → RoleBinding → Role → Permissions

Group Policies

When binding a role to a group, the subject includes a sub-relation:

// Group members inherit the role
app/rolebinding:policy456#bearer@app/group:engineering#member

All members of the engineering group automatically receive the role’s permissions.

Policy Usage with Check API

After creating policies, use the Check API to verify permissions.

Basic Permission Check

curl -L -X POST 'http://127.0.0.1:7400/v1beta1/check' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dGVzdC1jbGllbnQtaWQ6dGVzdC1zZWNyZXQ=' \
--data-raw '{
  "permission": "get",
  "resource": "compute/instance:92f69c3a-334b-4f25-90b8-4d4f3be6b825"
}'

How the Check Works

Extract Principal

Frontier extracts user credentials from:

Session cookies (if logged in)
Authorization header (Basic auth with client ID/secret)
Access token

Parse Resource

The resource string is parsed into namespace and ID:

compute/instance:92f69c3a-334b-4f25-90b8-4d4f3be6b825
Namespace: compute/instance
ID: 92f69c3a-334b-4f25-90b8-4d4f3be6b825

Query SpiceDB

Frontier asks SpiceDB: “Does user X have permission Y on resource Z?”

Graph Traversal

SpiceDB traverses the permission graph:

Find role bindings where user is bearer
Check if role has the requested permission
Verify role binding is granted on the resource

Return Decision

Returns true if a valid path exists, false otherwise

Resource Formats

The Check API accepts flexible resource formats:

Full Namespace
Alias
UUID
Custom Resource

{
  "permission": "update",
  "resource": "app/organization:acme-corp"
}

{
  "permission": "get",
  "resource": "org:acme-corp"
}

Aliases: org, organization → app/organization

{
  "permission": "delete",
  "resource": "app/project:92f69c3a-334b-4f25-90b8-4d4f3be6b825"
}

{
  "permission": "deploy",
  "resource": "compute/instance:prod-web-01"
}

Managing Policies via API

Create Policy

Assign a role to a user on a resource:

curl -L -X POST 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/policies' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
  "roleId": "app_organization_manager",
  "principalId": "550e8400-e29b-41d4-a716-446655440000",
  "principalType": "app/user"
}'

The roleId can be either the role UUID or role name (e.g., app_organization_manager). Frontier automatically resolves names to IDs.

List Policies

Retrieve policies for a resource:

curl -L -X GET 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/policies' \
-H 'Accept: application/json'

Delete Policy

Revoke a role assignment:

curl -L -X DELETE 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/policies/f47ac10b-58cc-4372-a567-0e02b2c3d479' \
-H 'Accept: application/json'

Deleting a policy:

Removes the policy record from Frontier
Deletes the app/rolebinding relations from SpiceDB
Immediately revokes the user’s access

Policy Internals

Understanding how policies work under the hood:

Policy Creation Process

Validate Role

Verify the role exists and retrieve its ID if a name was provided

Create Policy Record

Store the policy in Frontier’s database

Assign Role in SpiceDB

Create three SpiceDB relations:

// Bearer relation
relation.Create(ctx, {
  Object: {ID: policyID, Namespace: "app/rolebinding"},
  Subject: {ID: userID, Namespace: "app/user"},
  RelationName: "bearer"
})

// Role relation
relation.Create(ctx, {
  Object: {ID: policyID, Namespace: "app/rolebinding"},
  Subject: {ID: roleID, Namespace: "app/role"},
  RelationName: "role"
})

// Granted relation
relation.Create(ctx, {
  Object: {ID: resourceID, Namespace: resourceType},
  Subject: {ID: policyID, Namespace: "app/rolebinding"},
  RelationName: "granted"
})

Return Policy

Return the created policy object to the caller

Group Policy Sub-Relations

When the principal is a group:

subjectSubRelation := ""
if principalType == "app/group" {
    subjectSubRelation = "member"
}

relation.Create(ctx, {
    Object: {ID: policyID, Namespace: "app/rolebinding"},
    Subject: {
        ID: groupID, 
        Namespace: "app/group",
        SubRelationName: "member"  // Only group members get the role
    },
    RelationName: "bearer"
})

This ensures only members of the group inherit the role, not just anyone with access to the group object.

Hierarchical Role Based Access Control

Frontier implements hierarchical RBAC where permissions cascade through organizational structures.

Organization-Level Policies

Granting a role at the organization level provides access to:

The organization itself
All projects within the organization
All groups within the organization
Resources in those projects

This is implemented via synthetic permissions in the SpiceDB schema (e.g., project_get, group_update).

Example Hierarchy

Organization: ACME Corp
├── Project: Backend API
│   ├── Resource: compute/instance:prod-db
│   └── Resource: storage/bucket:api-logs
└── Project: Frontend
    └── Resource: compute/instance:web-server

A user with app_organization_owner on ACME Corp can:

Manage the organization
Access all projects (Backend API, Frontend)
Manage all resources in those projects

Real-World Policy Examples

Example 1: Organization Manager

Grant organization management access:

curl -L -X POST 'http://127.0.0.1:7400/v1beta1/organizations/acme-corp/policies' \
-H 'Content-Type: application/json' \
--data-raw '{
  "roleId": "app_organization_manager",
  "principalId": "[email protected]",
  "principalType": "app/user"
}'

Result: Alice can update organization details, create projects/groups, and manage service users.

Example 2: Project Viewer

Grant read-only project access:

curl -L -X POST 'http://127.0.0.1:7400/v1beta1/projects/backend-api/policies' \
-H 'Content-Type: application/json' \
--data-raw '{
  "roleId": "app_project_viewer",
  "principalId": "[email protected]",
  "principalType": "app/user"
}'

Result: Bob can view the Backend API project but cannot modify it.

Example 3: Custom Role Policy

Assign a custom shopping cart manager role:

curl -L -X POST 'http://127.0.0.1:7400/v1beta1/organizations/ecommerce-org/policies' \
-H 'Content-Type: application/json' \
--data-raw '{
  "roleId": "cart_manager",
  "principalId": "cart-service-account",
  "principalType": "app/serviceuser"
}'

Result: The cart service account can manage shopping carts with potato_cart_update, potato_cart_get, and potato_cart_delete permissions.

Example 4: Group-Based Access

Grant access to all engineering team members:

curl -L -X POST 'http://127.0.0.1:7400/v1beta1/projects/backend-api/policies' \
-H 'Content-Type: application/json' \
--data-raw '{
  "roleId": "app_project_manager",
  "principalId": "engineering-team",
  "principalType": "app/group"
}'

Result: All members of the engineering-team group can manage the Backend API project.

Policy Filtering and Listing

Retrieve policies with filters:

curl -L -X GET 'http://127.0.0.1:7400/v1beta1/policies?userId=550e8400-e29b-41d4-a716-446655440000' \
-H 'Accept: application/json'

Best Practices

Grant Least Privilege

Assign the minimum role necessary for users to perform their tasks. Use viewer roles for read-only access, manager roles for operational tasks, and owner roles sparingly.

Use Groups for Team Access

Instead of creating individual policies for each team member, create a group and assign the role to the group. This simplifies management and ensures consistency.

Leverage Hierarchical Permissions

Grant roles at the organization level when users need broad access, and at project/resource level for targeted permissions.

Regular Access Reviews

Periodically audit policies to ensure users still need their assigned roles. Remove policies for departed team members or changed responsibilities.

Use Service Accounts for Applications

Create service users and assign roles via policies for application-to-application authorization rather than using user credentials.

Document Custom Policies

Add metadata to policies explaining why specific access was granted, especially for custom roles or unusual assignments.

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

Policy Management

Policy Structure

How Policies Work

SpiceDB Relations Created

Group Policies

Policy Usage with Check API

Basic Permission Check

How the Check Works

Resource Formats

Managing Policies via API

Create Policy

List Policies

Delete Policy

Policy Internals

Policy Creation Process

Group Policy Sub-Relations

Hierarchical Role Based Access Control

Organization-Level Policies

Example Hierarchy

Real-World Policy Examples

Example 1: Organization Manager

Example 2: Project Viewer

Example 3: Custom Role Policy

Example 4: Group-Based Access

Policy Filtering and Listing

Best Practices

Next Steps

Examples

API Reference

Build docs developers (and LLMs) love

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

​Policy Structure

​How Policies Work

​SpiceDB Relations Created

​Group Policies

​Policy Usage with Check API

​Basic Permission Check

​How the Check Works

​Resource Formats

​Managing Policies via API

​Create Policy

​List Policies

​Delete Policy

​Policy Internals

​Policy Creation Process

​Group Policy Sub-Relations

​Hierarchical Role Based Access Control

​Organization-Level Policies

​Example Hierarchy

​Real-World Policy Examples

​Example 1: Organization Manager

​Example 2: Project Viewer

​Example 3: Custom Role Policy

​Example 4: Group-Based Access

​Policy Filtering and Listing

​Best Practices

​Next Steps

Examples

API Reference

Build docs developers (and LLMs) love

Policy Structure

How Policies Work

SpiceDB Relations Created

Group Policies

Policy Usage with Check API

Basic Permission Check

How the Check Works

Resource Formats

Managing Policies via API

Create Policy

List Policies

Delete Policy

Policy Internals

Policy Creation Process

Group Policy Sub-Relations

Hierarchical Role Based Access Control

Organization-Level Policies

Example Hierarchy

Real-World Policy Examples

Example 1: Organization Manager

Example 2: Project Viewer

Example 3: Custom Role Policy

Example 4: Group-Based Access

Policy Filtering and Listing

Best Practices

Next Steps