Role Management

A role is a collection of permissions that can be assigned to users, groups, or service accounts. Roles simplify access management by grouping related permissions together.

Role Structure

type Role struct {
    ID          string
    OrgID       string           // Empty for platform-wide roles
    Name        string           // e.g., "app_organization_owner"
    Title       string           // e.g., "Organization Owner"
    Permissions []string         // Permission slugs
    State       string           // "enabled" or "disabled"
    Scopes      []string         // Used for filtering
    Metadata    map[string]any
    CreatedAt   time.Time
    UpdatedAt   time.Time
}

How Roles Work

When a role is assigned to a user:

A policy is created binding the role to the user on a resource
The user inherits all permissions from that role
SpiceDB creates relationships between the role and permissions
Permission checks traverse these relationships to determine access

Predefined Roles

Frontier includes several predefined platform-wide roles.

Organization Roles

Owner
Manager
Access Manager
Viewer

app_organization_ownerFull administrative control over the organization and all resources within it.Permissions:

app_organization_administer

The administer permission hierarchically includes all other organization permissions.

app_organization_managerManage organization details and resources without full administrative access.Permissions:

app_organization_update
app_organization_get
app_organization_projectcreate
app_organization_projectlist
app_organization_groupcreate
app_organization_grouplist
app_organization_serviceusermanage
app_project_get
app_project_update

app_organization_accessmanagerManage user access and invitations without resource management.Permissions:

app_organization_invitationcreate
app_organization_invitationlist
app_organization_rolemanage
app_organization_policymanage

app_organization_viewerRead-only access to organization information.Permissions:

app_organization_get

Project Roles

Role	Permissions	Description
`app_project_owner`	`app_project_administer`	Full project administrative access
`app_project_manager`	`app_project_update` `app_project_get` `app_project_resourcelist` `app_organization_projectcreate` `app_organization_projectlist` `app_organization_grouplist`	Manage project details and resources
`app_project_viewer`	`app_project_get`	Read-only project access

Group Roles

Role	Permissions	Description
`app_group_owner`	`app_group_administer`	Full group administrative access
`app_group_member`	`app_group_get`	View group information

Billing Role

Role	Permissions	Description
`app_billing_manager`	`app_organization_billingview` `app_organization_billingmanage`	Manage organization billing

Custom Roles

Create custom roles to meet specific authorization requirements beyond predefined roles.

Platform vs Organization Roles

Platform Roles
Organization Roles

Created by: Frontier superusersScope: Available across all organizationsUse case: Standard roles used organization-wideOrgID: Empty string

Creating Custom Roles

Identify Required Permissions

Determine which permissions the role needs. Use permission slugs like potato_cart_update.

Choose Scope

Decide if the role should be platform-wide or organization-specific.

Create the Role

Use the API to create the role with appropriate permissions.

Assign via Policies

Bind the role to users through policies on specific resources.

Example: Shopping Cart Manager

Let’s create a custom role for managing shopping carts:

Create Organization Role

curl -L -X POST 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/roles' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
  "name": "cart_manager",
  "title": "Cart Manager",
  "permissions": [
    "potato_cart_update",
    "potato_cart_get",
    "potato_cart_delete"
  ],
  "metadata": {
    "description": "Manage shopping cart operations",
    "labels": {"team": "ecommerce"}
  }
}'

Permission slugs must exist before being added to a role. Create custom permissions first if needed.

Role States

Roles can be in one of two states:

Enabled
Disabled

Status: enabledThe role is active and can be assigned to users via policies. Users with this role can exercise its permissions.

Status: disabledThe role is deactivated. Users cannot exercise permissions from disabled roles, but the role definition is preserved.Use cases:

Temporary suspensions during investigations
Policy/compliance violations
Security concerns
Seasonal access patterns

Deactivating a Role

Temporarily disable a role without deleting it:

curl -L -X PUT 'http://127.0.0.1:7400/v1beta1/organizations/{orgId}/roles/{roleId}' \
-H 'Content-Type: application/json' \
--data-raw '{
  "state": "disabled"
}'

Reactivating a Role

Re-enable a disabled role:

curl -L -X PUT 'http://127.0.0.1:7400/v1beta1/organizations/{orgId}/roles/{roleId}' \
-H 'Content-Type: application/json' \
--data-raw '{
  "state": "enabled"
}'

Managing Roles via API

These APIs require special privileges. Authenticate with Client ID/Secret or Access Token.

List Organization Roles

Retrieve custom roles created within an organization:

List All Org Roles

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

Filter by state:

List Enabled Roles Only

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

This endpoint only returns organization-specific custom roles. Platform-wide default roles are not included.

List Platform Roles

Retrieve all predefined platform-wide roles:

curl -L -X GET 'http://127.0.0.1:7400/v1beta1/roles' \
-H 'Accept: application/json'

Filter by state:

curl -L -X GET 'http://127.0.0.1:7400/v1beta1/roles?state=enabled' \
-H 'Accept: application/json'

Create Organization Role

Create a custom role scoped to an organization:

curl -L -X POST 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/roles' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
  "name": "data_analyst",
  "title": "Data Analyst",
  "permissions": [
    "app_project_get",
    "app_project_resourcelist"
  ],
  "metadata": {
    "description": "Read-only access to project data"
  }
}'

Update Organization Role

Modify an existing custom role:

curl -L -X PUT 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/roles/c2d85306-96f4-4895-98b4-c3e5c2f3084d' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
  "name": "cart_manager",
  "title": "Cart Manager",
  "permissions": [
    "potato_cart_update",
    "potato_cart_get",
    "potato_cart_delete"
  ],
  "metadata": {
    "description": "Full cart management access"
  }
}'

Updating a role’s permissions automatically updates SpiceDB relationships for all existing policy assignments.

Delete Organization Role

Caution: Deleting a role is irreversible and permanently removes:

The role definition
All policies using this role
All user access granted through this role

Users will immediately lose access to resources granted via this role.

curl -L -X DELETE 'http://127.0.0.1:7400/v1beta1/organizations/4d726cf5-52f6-46f1-9c87-1a79f29e3abf/roles/c2d85306-96f4-4895-98b4-c3e5c2f3084d' \
-H 'Accept: application/json'

Role Implementation Details

When a role is created in Frontier:

1. Role-Permission Relations Created

For each permission in the role, Frontier creates SpiceDB relations:

// For user principals
app/role:cart_manager#potato_cart_update@app/user:*
app/role:cart_manager#potato_cart_get@app/user:*
app/role:cart_manager#potato_cart_delete@app/user:*

// For service user principals  
app/role:cart_manager#potato_cart_update@app/serviceuser:*
app/role:cart_manager#potato_cart_get@app/serviceuser:*
app/role:cart_manager#potato_cart_delete@app/serviceuser:*

The * wildcard means “all users who have this role will have these permissions.”

2. Dynamic Permission Updates

When updating a role:

Fetch Existing Role

Retrieve current role definition from database

Delete Old Relations

Remove all existing role-permission relationships from SpiceDB

Create New Relations

Establish new relationships for updated permissions

Update Database

Persist the updated role definition

Audit Record

Create audit trail of the role modification

3. Role Deletion Process

Deleting a role:

Removes all SpiceDB relations for the role
Deletes all policies using the role (cascading delete)
Removes the role from the database
Creates audit record of deletion

Best Practices

Use Predefined Roles When Possible

Leverage built-in roles like app_organization_owner before creating custom roles. They’re battle-tested and cover common scenarios.

Follow Least Privilege Principle

Grant only the minimum permissions required. Create narrow, focused roles rather than overly permissive ones.

Use Descriptive Names

Choose clear role names that indicate purpose (e.g., billing_viewer, project_deployer) rather than vague terms.

Document Custom Roles

Always add metadata with descriptions explaining the role’s purpose and intended users.

Prefer Disabling to Deleting

Temporarily disable roles instead of deleting them when access needs to be revoked. This preserves audit history.

Review Role Permissions Regularly

Periodically audit custom roles to ensure permissions still match organizational needs.

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

Role Structure

How Roles Work

Predefined Roles

Organization Roles

Project Roles

Group Roles

Billing Role

Custom Roles

Platform vs Organization Roles

Creating Custom Roles

Example: Shopping Cart Manager

Role States

Deactivating a Role

Reactivating a Role

Managing Roles via API

List Organization Roles

List Platform Roles

Create Organization Role

Update Organization Role

Delete Organization Role

Role Implementation Details

1. Role-Permission Relations Created

2. Dynamic Permission Updates

3. Role Deletion Process

Best Practices

Next Steps

Policies

Examples

Build docs developers (and LLMs) love

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

​Role Structure

​How Roles Work

​Predefined Roles

​Organization Roles

​Project Roles

​Group Roles

​Billing Role

​Custom Roles

​Platform vs Organization Roles

​Creating Custom Roles

​Example: Shopping Cart Manager

​Role States

​Deactivating a Role

​Reactivating a Role

​Managing Roles via API

​List Organization Roles

​List Platform Roles

​Create Organization Role

​Update Organization Role

​Delete Organization Role

​Role Implementation Details

​1. Role-Permission Relations Created

​2. Dynamic Permission Updates

​3. Role Deletion Process

​Best Practices

​Next Steps

Policies

Examples

Build docs developers (and LLMs) love

Role Structure

How Roles Work

Predefined Roles

Organization Roles

Project Roles

Group Roles

Billing Role

Custom Roles

Platform vs Organization Roles

Creating Custom Roles

Example: Shopping Cart Manager

Role States

Deactivating a Role

Reactivating a Role

Managing Roles via API

List Organization Roles

List Platform Roles

Create Organization Role

Update Organization Role

Delete Organization Role

Role Implementation Details

1. Role-Permission Relations Created

2. Dynamic Permission Updates

3. Role Deletion Process

Best Practices

Next Steps