WorkOS Docs Homepage
FGA
API referenceDashboardSign In
Getting StartedOverviewOverviewQuick StartQuick StartPlaygroundPlaygroundKey ConceptsSchemaSchemaWarrantsWarrantsResourcesResourcesPoliciesPoliciesQuery LanguageQuery LanguageWarrant TokensWarrant TokensOperations & UsageOperations & UsageManagementSchema ManagementSchema ManagementLocal DevelopmentLocal DevelopmentIdentity Provider SessionsIdentity Provider SessionsModelingOrg Roles & PermissionsOrg Roles & PermissionsCustom RolesCustom RolesGoogle DocsGoogle DocsEntitlementsEntitlementsUser GroupsUser GroupsManaged Service ProviderManaged Service ProviderAttribute-Based Access ControlAttribute-Based Access ControlConditional RolesConditional RolesPolicy ContextPolicy ContextPublic AccessPublic AccessSuperusersSuperusersBlocklistsBlocklists
API Reference
API Reference
Events
Events
Integrations
Integrations
Migrate to WorkOS
Migrate to WorkOS
SDKs
SDKs

Operations & Usage

Understand the operations_consumed metric and how it can help you optimize your FGA usage.

On this page

  • What is operations_consumed?
  • How Does It Work?
  • Implications of Graph Structure
  • Optimizing operations_consumed Usage
    • Sub-graph Separation
    • Favor Eventual Consistency
    • Cache Warrant Tokens
    • Simplify Relationships
  • Why operations_consumed Matters
  • Testing and Local Development

WorkOS Fine-Grained Authorization (FGA) empowers developers to design custom authorization models tailored to their specific needs using Access Control Lists (ACLs). In FGA, ACLs can inherit from one another through explicit connections or custom inheritance rules (see inheritance rules documentation). However, the flexibility of these models can complicate capacity planning for FGA quota.

FGA includes the operations_consumed metric in select API responses to provide visibility into quota consumption. This metric measures the computational cost of access checks, queries, and warrant transactions, offering developers valuable insights into how their authorization models affect quota usage.

Complex models with deeply nested data or intricate inheritance rules can significantly increase the computational cost of FGA transactions, making it critical to design models thoughtfully. By understanding the impact of these factors, developers can make informed decisions to balance functionality and efficiency.

This article breaks down the purpose of the operations_consumed metric, how it works, and strategies for optimizing FGA usage to better manage quota consumption.

What is operations_consumed?

operations_consumed is a metric that quantifies the number of computational operations performed during an ACL check or query in FGA. These operations include sub-tree checks and partial queries that are required to return the response. By tracking this value, FGA provides visibility into quota consumption, enabling developers to:

  • Understand the cost of their authorization checks.
  • Optimize their schema for better performance.
  • Ensure efficient usage within the provided quota.
POST /v1/check
{
"result": "authorized",
"is_implicit": true,
"operations_consumed": {
"total": 5
}
}

How Does It Work?

FGA performs access checks by traversing the ACL graph. The ACL graph is defined by warrant connections that are bridged by the inheritance rules defined in your schema. These operations include:

  1. Edge Traversals: Verifying ACL connectivity through adjacent resources using warrant relations.
  2. Inheritance Rules: Evaluating relationships based on inherited connections in your schema.
  3. Consistency Operations: Determining whether fully consistent or eventually consistent results are required.

In addition to schema complexity, the number of operations required to evaluate an access check also depends on sub-tree caching. Fully consistent checks inherently rely less on caching than eventually consistent checks. Eventually consistent checks have less strict cache policies, reducing the number of required sub-tree evaluations. However, requests for eventual consistency are not guaranteed to be served from cache. As a result, operations_consumed may vary slightly across requests, with the worst-case scenario involving no caching.

FGA handles cached operations as follows:

  • A single access check on cached data always counts as one operation.
  • Multiple checks on the same cached result within a single transaction each count as one operation.
  • Accessing cached sub-trees avoids evaluating the sub-tree, significantly optimizing query execution.

To optimize both performance and cost, it’s essential to use Warrant Tokens (see Warrant Token documentation) effectively and align your schema design with your consistency requirements.

Implications of Graph Structure

The structure of your ACL graph significantly impacts the operations_consumed metric. Here’s why:

  • Nested Graphs: While some nesting is acceptable, deeply nested relationships can significantly increase the complexity of access checks. Each additional layer in the graph requires more operations to resolve access, potentially impacting performance and query efficiency.
FGA diagram showing an ACL graph with nested connections
  • Wide Graphs: Graphs with many/all resources converging on a single node demand more operations per check to resolve access. As your application grows in size and complexity, more connections may focus on a single node. Performance may degrade and usage could increase.
FGA diagram showing a wide ACL tree
  • Sparse or Disjoint Graphs: Sparse graphs, where resources and subjects are minimally connected, consume fewer operations. Disjoint sub-graphs, typically separated by tenant or user, are particularly efficient. Both reduce the traversal scope.
FGA diagram showing disjoint graphs separated by company identifier

Optimizing operations_consumed Usage

To preserve operations and stay within quota limits, developers can utilize the following strategies:

Sub-graph Separation

Divide ACLs into smaller, independent sub-graphs. This approach reduces the traversal depth and isolates computational effort to specific areas of the graph. For example, building disjoint sub-graphs for different tenants that use your application.

Favor Eventual Consistency

Use fully consistent checks only when necessary. Opt for eventually consistent checks to increase the likelihood of cache hits. In practice, developers can avoid fully consistent checks by using Warrant Tokens in API requests.

Cache Warrant Tokens

Store API-generated Warrant Tokens with atomic writes to reuse them for future access checks, minimizing redundant computations. Cached warrant tokens reduce the need to use fully consistent checks.

Simplify Relationships

Avoid building a model with unnecessary nesting, complicated inheritance rules, or wide connections. Streamlining relationships minimizes the number of operations required to resolve an access check.

Why operations_consumed Matters

FGA charges based on operations_consumed usage, encouraging efficient graph design while providing the flexibility to build robust, scalable access control systems. Key benefits include:

  • Lower Costs: Reduce quota consumption with optimized graph structures.
  • Better Performance: Deliver faster response times for access checks and queries.
  • Scalability: Handle larger datasets efficiently without increased resource demands.

By optimizing operations_consumed, developers can create cost-effective, high-performing access control models that scale with their applications.

Testing and Local Development

WorkOS offers an isolated FGA Docker image designed for testing and development. This image utilizes SQLite and in-memory caching and is not intended for production use. It should be used only in a local environment or for running test suites in your CI/CD pipeline.

The fga-dev image is available on our public ECR repository. View the Usage section for more information about how to use it.

Schema ManagementLearn how to test, debug, and safely apply changes to your authorization schema and setup a GitOps workflow to automatically validate and apply changes to production
Up next
© WorkOS, Inc.
FeaturesAuthKitSingle Sign-OnDirectory SyncAdmin PortalFine-Grained Authorization
DevelopersDocumentationChangelogAPI Status
ResourcesBlogPodcastPricingSecuritySupport
CompanyAboutCustomersCareersLegalPrivacy
© WorkOS, Inc.