The FGA module is deprecated. Please use the Authorization API instead for all new implementations. The Fine-Grained Authorization (FGA) API provides a flexible authorization system based on relationship-based access control (ReBAC). This API is deprecated and maintained for backward compatibility only.
Initialize import { WorkOS } from '@workos-inc/node' ; const workos = new WorkOS ( 'sk_example_123456789' );
Methods Check if a subject has a specific relation to a resource.
const result = await workos . fga . check ({ checks: [ { resource: { resourceType: 'document' , resourceId: 'doc_123' }, relation: 'viewer' , subject: { resourceType: 'user' , resourceId: 'user_456' }, }, ], }); console . log ( result . isAuthorized ());
Operator for combining multiple checks (and, or).
checks
CheckWarrantOptions[]
required
Array of warrant checks to perform.
Enable debug mode for detailed decision tree.
Warrant token for consistent reads.
Whether the authorization is implicit.
Token for consistent reads.
Helper method to check if authorized.
checkBatch Perform multiple independent authorization checks.
const results = await workos . fga . checkBatch ({ checks: [ { resource: { resourceType: 'document' , resourceId: 'doc_123' }, relation: 'viewer' , subject: { resourceType: 'user' , resourceId: 'user_456' }, }, { resource: { resourceType: 'document' , resourceId: 'doc_789' }, relation: 'editor' , subject: { resourceType: 'user' , resourceId: 'user_456' }, }, ], }); results . forEach (( result ) => { console . log ( result . isAuthorized ()); });
checkOptions
CheckBatchOptions
required
checks
CheckWarrantOptions[]
required
Array of warrant checks to perform.
Array of check results, one for each check.
createResource Create a new FGA resource.
const resource = await workos . fga . createResource ({ resource: { resourceType: 'document' , resourceId: 'doc_123' , }, meta: { name: 'My Document' , owner: 'user_456' , }, });
resource
CreateResourceOptions
required
resource
ResourceInterface | ResourceOptions
required
Resource identifier.
Metadata for the resource.
The created resource object.
getResource Retrieve a resource by type and ID.
const resource = await workos . fga . getResource ({ resourceType: 'document' , resourceId: 'doc_123' , }); console . log ( resource . meta );
resource
ResourceInterface | ResourceOptions
required
listResources Retrieve a list of resources.
const resources = await workos . fga . listResources ({ resourceType: 'document' , search: 'contract' , limit: 20 , }); for await ( const resource of resources ) { console . log ( resource . resourceId , resource . meta ); }
Search query for resources.
Maximum number of records to return.
resources
AutoPaginatable<Resource>
An auto-paginatable list of resources.
updateResource Update a resource’s metadata.
const resource = await workos . fga . updateResource ({ resource: { resourceType: 'document' , resourceId: 'doc_123' , }, meta: { name: 'Updated Document Name' , }, });
options
UpdateResourceOptions
required
resource
ResourceInterface | ResourceOptions
required
Resource identifier.
The updated resource object.
deleteResource Delete a resource.
await workos . fga . deleteResource ({ resourceType: 'document' , resourceId: 'doc_123' , });
resource
DeleteResourceOptions
required
ID of the resource to delete.
batchWriteResources Create or delete multiple resources in a single operation.
const resources = await workos . fga . batchWriteResources ({ op: 'CREATE' , resources: [ { resource: { resourceType: 'document' , resourceId: 'doc_123' }, meta: { name: 'Document 1' }, }, { resource: { resourceType: 'document' , resourceId: 'doc_456' }, meta: { name: 'Document 2' }, }, ], });
options
BatchWriteResourcesOptions
required
Operation: CREATE or DELETE.
resources
CreateResourceOptions[] | DeleteResourceOptions[]
required
Array of resources to create or delete.
Array of created/deleted resources.
writeWarrant Create or delete a warrant (relationship between subject and resource).
const warrantToken = await workos . fga . writeWarrant ({ op: 'CREATE' , resource: { resourceType: 'document' , resourceId: 'doc_123' }, relation: 'viewer' , subject: { resourceType: 'user' , resourceId: 'user_456' }, }); console . log ( warrantToken . token );
options
WriteWarrantOptions
required
Operation: CREATE or DELETE (default: CREATE).
resource
ResourceInterface | ResourceOptions
required
Resource identifier.
Relation type (e.g., ‘viewer’, ‘editor’, ‘owner’).
subject
ResourceInterface | Subject
required
Subject (user or group) to grant/revoke relation.
Policy string for conditional access.
Warrant token for consistent reads.
batchWriteWarrants Create or delete multiple warrants in a single operation.
const warrantToken = await workos . fga . batchWriteWarrants ([ { op: 'CREATE' , resource: { resourceType: 'document' , resourceId: 'doc_123' }, relation: 'viewer' , subject: { resourceType: 'user' , resourceId: 'user_456' }, }, { op: 'CREATE' , resource: { resourceType: 'document' , resourceId: 'doc_123' }, relation: 'editor' , subject: { resourceType: 'user' , resourceId: 'user_789' }, }, ]);
options
WriteWarrantOptions[]
required
Array of warrant write operations.
Warrant token for consistent reads.
listWarrants Retrieve a list of warrants.
const warrants = await workos . fga . listWarrants ({ resourceType: 'document' , resourceId: 'doc_123' , limit: 20 , }); for await ( const warrant of warrants ) { console . log ( warrant . relation , warrant . subject ); }
Filter by subject relation.
Maximum number of records to return.
An auto-paginatable list of warrants.
Query for resources or subjects based on warrants.
const results = await workos . fga . query ({ select: 'subject' , resourceType: 'document' , resourceId: 'doc_123' , relation: 'viewer' , }); for await ( const result of results ) { console . log ( result . resourceType , result . resourceId ); }
select
'resource' | 'subject'
required
What to query for.
Resource type to filter by.
Resource ID to filter by.
Subject type to filter by.
Subject relation to filter by.
Policy context for conditional queries.
results
FgaPaginatable<QueryResult>
A paginatable list of query results.
Migration Guide To migrate from FGA to the Authorization API:
Replace workos.fga.check() with workos.authorization.check()
Replace resource management with workos.authorization.createResource(), etc.
Use workos.authorization.assignRole() instead of warrant operations
See the Authorization API documentation for complete details
Example: Access Control with FGA // Create resources await workos . fga . createResource ({ resource: { resourceType: 'document' , resourceId: 'doc_123' }, meta: { name: 'Confidential Report' }, }); // Grant viewer access await workos . fga . writeWarrant ({ resource: { resourceType: 'document' , resourceId: 'doc_123' }, relation: 'viewer' , subject: { resourceType: 'user' , resourceId: 'user_456' }, }); // Check access const result = await workos . fga . check ({ checks: [ { resource: { resourceType: 'document' , resourceId: 'doc_123' }, relation: 'viewer' , subject: { resourceType: 'user' , resourceId: 'user_456' }, }, ], }); if ( result . isAuthorized ()) { console . log ( 'Access granted' ); }