Query

Use the Query Language to list the set of subjects that have access to a particular resource or to list the set of resources a particular subject has access to.

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const queryResponse = await workos.fga.query({
  q: 'select pricing-tier, feature where user:12 is member',
});

console.log(queryResponse.data);

Fine-Grained Authorization

Fine-Grained Authorization (FGA) is a set of APIs designed to help you implement scalable, centralized, fine grained authorization in your application.

Check

Check if a subject has a particular relation on a resource.

Single Check

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const checkResult = await workos.fga.check({
  checks: [
    {
      resource: {
        resourceType: 'report',
        resourceId: 'avk2837',
      },
      relation: 'viewer',
      subject: {
        resourceType: 'user',
        resourceId: '5djfs6',
      },
    },
  ],
});

if (checkResult.isAuthorized()) {
  console.log('User is authorized to view the report');
}

Multiple Checks

 import { WorkOS, CheckOp } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const checkResult = await workos.fga.check({
  op: CheckOp.AllOf,
  checks: [
    {
      resource: {
        resourceType: 'report',
        resourceId: 'avk2837',
      },
      relation: 'viewer',
      subject: {
        resourceType: 'user',
        resourceId: '5djfs6',
      },
    },
    {
      resource: {
        resourceType: 'report',
        resourceId: 'lal2420',
      },
      relation: 'viewer',
      subject: {
        resourceType: 'user',
        resourceId: '5djfs6',
      },
    },
  ],
});

if (checkResult.isAuthorized()) {
  console.log('User is authorized to view the reports');
}

Batch Check

Executes a batch of checks and returns a list of results in a single operation.

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const checkResults = await workos.fga.checkBatch({
  checks: [
    {
      resource: {
        resourceType: 'report',
        resourceId: 'avk2837',
      },
      relation: 'viewer',
      subject: {
        resourceType: 'user',
        resourceId: '5djfs6',
      },
    },
    {
      resource: {
        resourceType: 'report',
        resourceId: 'slp1029',
      },
      relation: 'viewer',
      subject: {
        resourceType: 'user',
        resourceId: '5djfs6',
      },
    },
  ],
});

List warrants

Get a list of all your existing warrants matching the criteria specified.

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const warrants = await workos.fga.listWarrants();

console.log(warrants.data);

Warrant

Represents a relation between resources in your application.

Warrant

 const warrant = {
  resourceType: 'report',
  resourceId: '23ft346',
  relation: 'editor',
  subject: {
    resourceType: 'user',
    resourceId: '15ads7823a9df7as433gk23dd',
  },
};

Delete a warrant

Deletes a warrant in the current environment.

 import { WorkOS, WarrantOp } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const warrantResponse = await workos.fga.writeWarrant({
  op: WarrantOp.Delete,
  resource: {
    resourceType: 'report',
    resourceId: '23ft346',
  },
  relation: 'editor',
  subject: {
    resourceType: 'user',
    resourceId: '15ads7823a9df7as433gk23dd',
  },
});

Create a warrant

Creates a new warrant in the current environment.

 import { WorkOS, WarrantOp } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const warrantResponse = await workos.fga.writeWarrant({
  op: WarrantOp.Create,
  resource: {
    resourceType: 'report',
    resourceId: '23ft346',
  },
  relation: 'editor',
  subject: {
    resourceType: 'user',
    resourceId: '15ads7823a9df7as433gk23dd',
  },
});

Batch Write Warrants

Executes a batch of warrant writes in the current environment.

 import { WorkOS, WarrantOp } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const warrantResponse = await workos.fga.batchWriteWarrants([
  {
    op: WarrantOp.Delete,
    resource: {
      resourceType: 'report',
      resourceId: '23ft346',
    },
    relation: 'viewer',
    subject: {
      resourceType: 'user',
      resourceId: '15ads7823a9df7as433gk23dd',
    },
  },
  {
    op: WarrantOp.Create,
    resource: {
      resourceType: 'report',
      resourceId: '23ft346',
    },
    relation: 'editor',
    subject: {
      resourceType: 'user',
      resourceId: '15ads7823a9df7as433gk23dd',
    },
  },
  {
    resource: {
      resourceType: 'report',
      resourceId: '46hn681',
    },
    relation: 'editor',
    subject: {
      resourceType: 'user',
      resourceId: '15ads7823a9df7as433gk23dd',
    },
  },
]);

Update a resource type

Update properties of a resource type.

cURL

 curl "https://api.workos.com/fga/v1/resource-types/report" \
  -X PUT \
  -H "Authorization: Bearer sk_example_123456789" \
  --data-raw \
  '{
    "relations": {
      "parent": {},
      "owner": {},
      "editor": {},
      "viewer": {}
    }
  }'

List resource types

Get a list of all your existing resource types matching the criteria specified.

cURL

 curl https://api.workos.com/fga/v1/resource-types \
  --header "Authorization: Bearer sk_example_123456789"

Resource Type

Represents a type of resource and its possible relationships in your application. See Resource Types to learn more about relation rules. See JSON Syntax for more examples.

Resource Type

cURL

 {
  "type": "report",
  "relations": {
    "parent": {},
    "owner": {},
    "editor": {
      "inherit_if": "owner"
    },
    "viewer": {
      "inherit_if": "any_of",
      "rules": [
        {
          "inherit_if": "editor"
        },
        {
          "inherit_if": "viewer",
          "of_type": "report",
          "with_relation": "parent"
        }
      ]
    }
  }
}

Get a resource type

Get the definition of an existing resource type.

cURL

 curl https://api.workos.com/fga/v1/resource-types/report \
  --header "Authorization: Bearer sk_example_123456789"

Delete a resource type

Deletes a resource type in the current environment.

Request

cURL

 curl --request DELETE \
  --url https://api.workos.com/fga/v1/resource-types/report \
  --header "Authorization: Bearer sk_example_123456789"

Create a resource type

Create a new resource type in the current environment.

cURL

 curl "https://api.workos.com/fga/v1/resource-types" \
  -X POST \
  -H "Authorization: Bearer sk_example_123456789" \
  --data-raw \
  '{
    "type": "report",
    "relations": {
      "parent": {},
      "owner": {},
      "editor": {
        "inherit_if": "owner"
      },
      "viewer": {
        "inherit_if": "any_of",
        "rules": [
          {
            "inherit_if": "editor"
          },
          {
            "inherit_if": "viewer",
            "of_type": "report",
            "with_relation": "parent"
          }
        ]
      }
    }
  }'

Apply resource types

Sets resource types in the current environment to match the provided resource types.

This endpoint performs a batch operation which will override your entire schema for the environment. Any existing resource types not included in the request will be deleted.

cURL

 curl "https://api.workos.com/fga/v1/resource-types" \
  -X PUT \
  -H "Authorization: Bearer sk_example_123456789" \
  --data-raw \
  '[
    {
      "type": "user",
      "relations": {}
    },
    {
      "type": "role",
      "relations": {
        "member": {
          "allowed_types": ["user"]
        }
      }
    }
  ]'

Update a resource

Update the meta of an existing resource in the current environment.

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const resource = await workos.fga.updateResource({
  resource: {
    resourceType: 'user',
    resourceId: 'd6ed6474-784e-407e-a1ea-42a91d4c52b9',
  },
  meta: {
    email: 'updated@email.com',
  },
});

List resources

Get a list of all your existing resources matching the criteria specified.

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const resources = await workos.fga.listResources();

console.log(resources.data);

Resource

Represents a resource in your application.

Resource

 const resource = {
  resourceType: 'user',
  resourceId: 'dkfi7a0s-784e-407e-a1ea-42a91d4c52b9',
};

Get a resource

Get an existing resource.

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const warrants = await workos.fga.getResource({
  resourceType: 'user',
  resourceId: 'd6ed6474-784e-407e-a1ea-42a91d4c52b9',
});

Delete a resource

Deletes a resource in the current environment.

Deleting a resource will also delete all warrants where the resource is the resource or subject of the warrant.

Request

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.fga.deleteResource({
  resourceType: 'user',
  resourceId: 'd6ed6474-784e-407e-a1ea-42a91d4c52b9',
});

Create a resource

Create a new resource in the current environment.

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const resource = await workos.fga.createResource({
  resource: {
    resourceType: 'user',
    resourceId: 'd6ed6474-784e-407e-a1ea-42a91d4c52b9',
  },
});

Batch write resources

Create or delete up to 100 resources in one request.

Batch create resources

 import { WorkOS, ResourceOp } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const resources = await workos.fga.batchWriteResources({
  op: ResourceOp.Create,
  resources: [
    {
      resource: {
        resourceType: 'user',
        resourceId: 'user-1',
      },
      meta: {
        email: 'user1@example.com',
      },
    },
    {
      resource: {
        resourceType: 'user',
        resourceId: 'user-2',
      },
    },
    {
      resource: {
        resourceType: 'user',
      },
    },
  ],
});

Batch delete resources

 import { WorkOS, ResourceOp } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const deletedResources = await workos.fga.batchWriteResources({
  op: ResourceOp.Delete,
  resources: [
    {
      resourceType: 'user',
      resourceId: 'user-1',
    },
    {
      resourceType: 'user',
      resourceId: 'user-2',
    },
    {
      resourceType: 'user',
      resourceId: 'generated-user-id',
    },
  ],
});

Update a policy

Update properties of a policy.

cURL

 curl "https://api.workos.com/fga/v1/policies/ip_equal" \
  -X PUT \
  -H "Authorization: Bearer sk_example_123456789" \
  --data-raw \
  '{
     "description": "Check if the client IP is in the range 192.168.x.x",
     "language": "expr",
     "parameters": [
       {
         "name": "clientIp",
         "type": "string"
       }
     ],
     "expression": "clientIp matches \"192\\\\.168\\\\..*\\\\..*\""
   }
'

List policies

Get a list of all your existing policies matching the criteria specified.

cURL

 curl https://api.workos.com/fga/v1/policies \
  --header "Authorization: Bearer sk_example_123456789"

Policy

Represents a policy that defines the access control rules for your application.

Policy

cURL

 {
  "name": "ip_equal",
  "description": "Check if the client IP is in the range 192.168.x.x",
  "language": "expr",
  "parameters": [
    {
      "name": "clientIp",
      "type": "string"
    }
  ],
  "expression": "clientIp matches \"192\\\\.168\\\\..*\\\\..*\""
}

Get a policy

Get the definition of an existing policy.

cURL

 curl https://api.workos.com/fga/v1/policies/ip_equal \
  --header "Authorization: Bearer sk_example_123456789"

Delete a policy

Deletes a policy in the current environment.

Request

cURL

 curl --request DELETE \
  --url https://api.workos.com/fga/v1/policies/ip_equal \
  --header "Authorization: Bearer sk_example_123456789"

Create a policy

Create a new policy in the current environment.

cURL

 curl "https://api.workos.com/fga/v1/policies" \
  -X POST \
  -H "Authorization: Bearer sk_example_123456789" \
  --data-raw \
  '{
       "name": "ip_equal",
       "description": "Check if the client IP is in the range 192.168.x.x",
       "language": "expr",
       "parameters": [
           {
               "name": "clientIp",
               "type": "string"
           }
       ],
       "expression": "clientIp matches \"192\\\\.168\\\\..*\\\\..*\""
   }'

Schema

Represents the authorization model in your FGA environment. Includes resource type definitions and policies that define how authorization checks are processed.

Schema

cURL

 {
  "version": "0.3",
  "resource_types": [
    {
      "type": "user"
    },
    {
      "type": "group",
      "relations": {
        "member": {
          "allowed_types": ["user"]
        }
      }
    },
    {
      "type": "asset",
      "relations": {
        "service_manager": {
          "allowed_types": ["group"]
        },
        "access_diagnostics": {
          "allowed_types": [],
          "inherit_if": "all_of",
          "rules": [
            {
              "inherit_if": "member",
              "of_type": "group",
              "with_relation": "service_manager"
            },
            {
              "policy": "is_in_geo_fence"
            }
          ]
        }
      }
    }
  ],
  "policies": {
    "is_in_geo_fence": {
      "parameters": [
        {
          "name": "user_location",
          "type": "map"
        },
        {
          "name": "geofence",
          "type": "map"
        }
      ],
      "expression": "user_location.lat >= geofence.min_lat && user_location.lat <= geofence.max_lat && user_location.lon >= geofence.min_lon && user_location.lon <= geofence.max_lon"
    }
  }
}

Get a schema

Get the authorization model for your current environment.

cURL

 curl https://api.workos.com/fga/v1/schema \
  --header "Authorization: Bearer sk_example_123456789"

Apply schema

Sets resource types and policies in the current environment.

This endpoint performs a batch operation which will override your entire schema for the environment. Any existing resource types and policies not included in the request will be deleted.

cURL

 curl "https://api.workos.com/fga/v1/schema" \
  -X POST \
  -H "Authorization: Bearer sk_example_123456789" \
  --data-raw \
  '{
    "resource_types": [
      {
        "type": "user",
        "relations": {}
      },
      {
        "type": "role",
        "relations": {
          "member": {
            "allowed_types": ["user"]
          }
        }
      }
    ],
    "policies": {}
  }'