Superusers

Learn how to use policies to create superuser overrides.

Explore the example from this guide in the FGA Playground, where you can interact with the schema, warrants, and access checks in real-time!

Superuser policies allow specific users to override inheritance rules to grant broad access to many resources. This is useful for granting elevated privileges to trusted users, such as administrators, support engineers, or internal employees.

When to Use It?

Use superuser policies when you need to:

Provide emergency access to a resource without modifying existing permissions.

Allow internal employees to manage resources without explicitly assigning them to each one.

Implement organization-wide administrative roles that apply across multiple resources.

Example Applications

Many applications implement superuser policies, including:

E-commerce platforms: Store administrators or support agents need access to all stores for troubleshooting.

Multi-tenant SaaS applications: Internal employees may need to access any tenant’s data for support purposes.

Content management systems: Superusers may need the ability to edit or review content across multiple projects.

Schema

 version 0.3

type user

type store
  relation editor [user]
  relation viewer [user]

  // Editors of a store are either
  //   Assigned directly as an editor of the store
  //   Or superusers who can edit any store (via is_superuser policy)
  inherit editor if
      policy is_superuser

  // Any editor can also view the store
  inherit viewer if
    relation editor

policy is_superuser(user_attributes map) {
  user_attributes.superuser == true &&
    user_attributes.email endsWith "@internal-domain.com"
}

Example

1. Apply the schema

Create a file called schema.txt containing the schema definition from above. Then use the CLI to apply this schema to your WorkOS FGA environment.

Note: make sure to select the correct environment with the CLI

 workos fga schema apply schema.txt

2. Check access

With our environment setup, we can check the user’s permission to view a document.

Check if a user can view a store

 curl "https://api.workos.com/fga/v1/check" \
  -X POST \
  -H "Authorization: Bearer sk_example_123456789" \
  --data-raw \
  '{
    "checks": [
      {
        "resource_type": "store",
        "resource_id": "store-1",
        "relation": "viewer",
        "subject": {
          "resource_type": "user",
          "resource_id": "user_2oDscjroNWtzxzYEnEzT9P7VYEe"
        },
        "context": {
          "user_attributes": {
            "id": "user_2oDscjroNWtzxzYEnEzT9P7VYEe",
            "email": "john.doe@internal-domain.com",
            "superuser": true
          }
        }
      }
    ]
  }'