OpenFGA Best Practices

Comprehensive guide for authoring OpenFGA authorization models and using OpenFGA SDKs, maintained for AI agents and developers. Contains rules across 7 categories covering core concepts, relationship patterns, testing, custom roles, model optimization, and language-specific SDK usage.

When to Apply

Reference these guidelines when:

• Creating new OpenFGA authorization models
• Defining types and relations in .fga files
• Writing relationship tuples
• Testing models with .fga.yaml files
• Implementing custom roles
• Reviewing or refactoring existing models
• Integrating OpenFGA with JavaScript/TypeScript, Go, Python, Java, or .NET applications

Rule Categories by Priority

Quick Reference

1. Core Concepts (CRITICAL)

• core-types – Define types for all entity classes
• core-schema-version – Always use schema 1.1
• core-relations – Define relations on object types, not user types
• core-tuples – Write relationship tuples to establish facts
• core-separation – Separate schema (model) from data (tuples)

2. Relationship Definitions (CRITICAL)

• relation-direct – Use [type] for direct assignments
• relation-concentric – Use or for permission inheritance
• relation-indirect – Use X from Y for hierarchical access
• relation-usersets – Use type#relation for group-based access
• relation-conditions – Use CEL conditions for contextual authorization
• relation-wildcards – Use type:* for public access carefully
• relation-wildcards-as-booleans – To use type:*to model boolan attributes

3. Model Design (HIGH)

• design-permissions – Define can_* relations for permissions
• design-hierarchy – Model parent-child relationships correctly
• design-organization – Structure organization-level access
• design-naming – Use clear, consistent naming conventions
• design-modules – Split a model in modules for collaboration among multiple teams.

4. Testing & Validation (HIGH)

• test-fga-yaml – Structure tests in .fga.yaml files
• test-check-assertions – Write check assertions for permission verification
• test-list-objects – Test list_objects queries
• test-list-users – Test list_users queries
• test-conditions – Test conditional relationships with context
• test-cli – Use OpenFGA CLI for model testing

5. Custom Roles (MEDIUM)

• roles-simple – Implement simple user-defined roles
• roles-assignments – Use role assignments for resource-specific roles
• roles-static-combo – Combine static and custom roles
• roles-when-to-use – Choose the right role pattern

6. Optimization (MEDIUM)

• optimize-simplify – Remove unused types and relations
• optimize-tuples – Use indirect relationships to reduce tuple count
• optimize-type-restrictions – Apply appropriate type restrictions

7. SDK Integration (HIGH)

• sdk-javascript – JavaScript/TypeScript SDK usage
• sdk-go – Go SDK usage
• sdk-python – Python SDK usage (async and sync)
• sdk-java – Java SDK usage
• sdk-dotnet – .NET SDK usage

8. Workflow (CRITICAL)

• workflow-validate – Always validate models before delivery

How to Use

Read individual rule files for detailed explanations and code examples:

rules/core-types.md
rules/relation-concentric.md
rules/test-fga-yaml.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md