Openfga

OpenFGA Best Practices

Use this skill to design and review OpenFGA models end to end: define types and relations, write tuples, derive can_* permissions, choose usersets and inheritance patterns, and validate behavior with .fga.yaml tests and CLI checks.

Quick Start Example

Minimal model:

model
  schema 1.1

type user

type organization
  relations
    define admin: [user]
    define member: [user] or admin

type document
  relations
    define organization: [organization]
    define owner: [user]
    define can_edit: owner or admin from organization
    define can_view: can_edit or member from organization

Example tuples:

organization:acme#admin@user:alice
document:roadmap#organization@organization:acme
document:roadmap#owner@user:bob

Example test targets:

• check that user:alice can view and edit document:roadmap
• check that user:bob can edit their own document
• list_users for document:roadmap#can_view
• list_objects for documents user:alice can edit

How to Use

When a workflow step points to a rule ID, open the matching file in references/ for detailed guidance and examples.

Note: SDK references (sdk-*.md) are only needed for integration tasks — skip them during pure model authoring and testing.

Rule Index

Core

| File | Description | |------|-------------| | references/core-types.md | Define types for entity classes | | references/core-relations.md | Relations belong on object types | | references/core-tuples.md | Relationship tuples as facts | | references/core-separation.md | Model vs data separation | | references/core-schema-version.md | Schema version |

Relations

| File | Description | |------|-------------| | references/relation-direct.md | Direct relationships | | references/relation-indirect.md | Indirect relationships with X from Y | | references/relation-concentric.md | Concentric relationships | | references/relation-usersets.md | Usersets for group-based access | | references/relation-conditions.md | Conditional relationships | | references/relation-wildcards.md | Wildcards for public access | | references/relation-wildcards-as-booleans.md | Wildcards for boolean attributes |

Design

| File | Description | |------|-------------| | references/design-permissions.md | Define permissions with can_ relations | | references/design-hierarchy.md | Hierarchical structures | | references/design-organization.md | Organization-level access | | references/design-create-on-parent.md | Check create permissions on parent objects | | references/design-naming.md | Naming conventions | | references/design-modules.md | Modularize models (only when asked) |

Roles

| File | Description | |------|-------------| | references/roles-simple.md | Simple static roles | | references/roles-static-combo.md | Combining static and custom roles | | references/roles-assignments.md | Role assignments for resource-specific roles | | references/roles-when-to-use.md | When to use each role pattern |

Optimization

| File | Description | |------|-------------| | references/optimize-simplify.md | Simplify models | | references/optimize-tuples.md | Minimize tuple count | | references/optimize-type-restrictions.md | Type restrictions |

Testing

| File | Description | |------|-------------| | references/test-fga-yaml.md | Structure tests in .fga.yaml | | references/test-check-assertions.md | Check assertions | | references/test-list-objects.md | List objects tests | | references/test-list-users.md | List users tests | | references/test-conditions.md | Testing conditions | | references/test-cli.md | OpenFGA CLI usage | | references/workflow-validate.md | Always validate models |

SDKs (for integration tasks only)

| File | Description | |------|-------------| | references/sdk-javascript.md | JavaScript/TypeScript SDK | | references/sdk-go.md | Go SDK | | references/sdk-python.md | Python SDK | | references/sdk-java.md | Java SDK | | references/sdk-dotnet.md | .NET SDK |

Recommended Workflow

1. Model the resource graph.

Define types, direct relations, inheritance edges, and can_* permissions. Rules to check first: core-*, relation-*, design-permissions, design-hierarchy.

1. Add tuples and test intent.

Add representative tuples and cover expected behavior with check, list_objects, and list_users tests. Rules to check next: core-tuples, test-fga-yaml, test-check-assertions, test-list-objects, test-list-users.

1. Review parent-child creation and deletion paths.

Verify each parent -> child edge has create permissions on the parent and that no child permission is directly grantable unless intended. Rules to check: design-create-on-parent, relation-direct, design-permissions.

1. Simplify before removing schema.

Before deleting any type or relation, confirm it is not referenced by permissions, tuples, or tests. If a simplification breaks a reference: restore the relation or update the model/tests, then re-run this step. Rules to check: optimize-simplify, optimize-tuples, optimize-type-restrictions.

1. Validate the model.

Run:

fga model validate --file stores//model.fga

If validation fails: read the reported relation or type errors, fix the model, and re-run validation before continuing.

1. Run the store tests.

Run:

fga model test --tests stores//store.fga.yaml

If tests fail: update tuples, assertions, or permission definitions, then re-run tests until all checks and list queries pass.

1. Only then finalize delivery.

For touched stores, finish only after validation and tests are green. Final rule to check: workflow-validate.

Full Compiled Document

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: openfga
• Source: openfga/agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.