Checking Relations

Now that you've created your definitions and relations, you can check them to determine access control.

Most of our SDKs provide a check function, which is the primary method for checking relations. This function checks if the given relations are satisfied and returns detailed results.

Check if relation exists

The check function checks if the given relations are satisfied. Pass in an array of FGARelation objects and the function returns an array of FGACheck results indicating whether each relation is allowed.

const relations = [
  {
    resource: 'some-doc',
    resourceType: 'doc',
    relation: 'can_view',
    target: 'u1',
    targetType: 'user',
  },
];

const checks = await descopeClient.management.fga.check(relations);
// checks[0].allowed indicates if the relation is satisfied

# Check if the given relations are satisfied
# Args:
# relations (List[dict]): List of relation queries each in the format of:
#     {
#         "resource": "id of the resource that has the relation",
#         "resourceType": "the type of the resource (namespace)",
#         "relation": "the relation definition for the relation",
#         "target": "the target that has the relation - usually users or other resources",
#         "targetType": "the type of the target (namespace)"
#     }
#
# Return value (List[dict]):
# Return List in the format
#       [
#         {
#             "allowed": True|False,
#             "relation": {
#                 "resource": "id of the resource that has the relation",
#                 "resourceType": "the type of the resource (namespace)",
#                 "relation": "the relation definition for the relation",
#                 "target": "the target that has the relation - usually users or other resources",
#                 "targetType": "the type of the target (namespace)"
#             }
#         }
#     ]
# Raise:
# AuthException: raised if query fails
checks = descope_client.mgmt.fga.check(
    [
        {
            "resource": "some-doc",
            "resourceType": "doc",
            "relation": "viewer",
            "target": "u1",
            "targetType": "user",
        }
    ]
)
# checks[0]["allowed"] indicates if the relation is satisfied

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()

checks, err := descopeClient.Management.FGA().Check(ctx, []*descope.FGARelation{
    {
        Resource:     "some-doc",
        ResourceType: "doc",
        Relation:     "can_view",
        Target:       "u1",
        TargetType:   "user",
    },
})
if err != nil {
    // handle error
}

// checks[0].Allowed indicates if the relation is satisfied

FGAService fs = descopeClient.getManagementServices().getFgaService();

List<FGARelation> relations = Arrays.asList(
    new FGARelation("some-doc", "doc", "can_view", "u1", "user")
);

try {
    List<FGACheckResult> results = fs.check(relations);
    for (FGACheckResult result : results) {
        // result.isAllowed() indicates if the relation is satisfied
    }
} catch (DescopeException de) {
    // Handle the error
}

Check who can access a particular resource

The whoCanAccess function takes in a resource, a relation definition, and a namespace corresponding to the relation definition and returns an array of users with the given relation definitions to the resource.

const resource: string = "The resource of a relation";
const relationDefinition: string = "The relation definition name";
const namespace: string = "The relation definition namespace";

const users: string[] = await descopeClient.management.authz.whoCanAccess(resource, relationDefinition, namespace);

#  Finds the list of targets (usually users) who can access the given resource with the given RD
# Args:
# resource (str): the resource we are checking
# relation_definition (str): the RD we are checking
# namespace (str): the namespace for the RD

# Return value (List[str]): list of targets (user IDs usually that have the access)
# Raise:
# AuthException: raised if query fails
client.mgmt.authz.who_can_access("a", "b", "c")

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()

mgmt.Authz().WhoCanAccess(ctx, "r", "rd", "")

var respWho = authzService.whoCanAccess("roadmap.ppt", "editor", "doc");

Check what relations a resource has

The resourceRelations function returns an array of relations for a given resource.

const resource: string = "The resource for the relations";

const relations: AuthzRelation[] = descopeClient.management.authz.resourceRelations(resource);

#  Returns the list of all defined relations (not recursive) on the given resource.
# Args:
# resource (str): the resource we are listing relations for

# Return value (List[dict]):
# Return List of relations each in the format of a relation as documented in create_relations
# Raise:
# AuthException: raised if query fails
client.mgmt.authz.resource_relations("a")

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()


res, err := mgmt.Authz().ResourceRelations(ctx, "r")

var respResourceRelations = authzService.resourceRelations("roadmap.ppt");

Check what relations a resource has (with target set filter)

The ResourceRelationsWithTargetSetsFilter function returns relations for a given resource with an option to include or exclude target set relations.

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
//    resource: the resource to get relations for
//    includeTargetSetRelations: whether to include relations where the target is a set (group)
ctx := context.Background()

// Get relations including target set relations
res, err := descopeClient.Management.Authz().ResourceRelationsWithTargetSetsFilter(ctx, "r", true)

// Get relations excluding target set relations
res, err := descopeClient.Management.Authz().ResourceRelationsWithTargetSetsFilter(ctx, "r", false)

Check what relations a target has directly

The targetsRelations function takes an array of targets (eg. users) and returns an array of relations that exist for the target directly.

This will NOT return relations that exist for the target implicitly, such as through a parent node with a matching relation definition.

const targets: string[] = ["The targets to check relations for directly."];

const relations: AuthzRelation[] = descopeClient.management.authz.targetsRelations(targets);

# Returns the list of all defined relations (not recursive) for the given targets.
# Args:
# targets (List[str]): the list of targets we are returning the relations for

# Return value (List[dict]):
# Return List of relations each in the format of a relation as documented in create_relations
# Raise:
# AuthException: raised if query fails
client.mgmt.authz.targets_relations(["a"])

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()


res, err := mgmt.Authz().TargetsRelations(ctx, []string{"u1"})


var respUsersRelations = authzService.targetsRelations(List.of("u1"));

Check what relations a target has directly (with target set filter)

The TargetsRelationsWithTargetSetsFilter function returns relations for given targets with an option to include or exclude target set relations.

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
//    targets: the list of targets to get relations for
//    includeTargetSetRelations: whether to include relations where the target is a set (group)
ctx := context.Background()


// Get relations including target set relations
res, err := descopeClient.Management.Authz().TargetsRelationsWithTargetSetsFilter(ctx, []string{"u1"}, true)

// Get relations excluding target set relations
res, err := descopeClient.Management.Authz().TargetsRelationsWithTargetSetsFilter(ctx, []string{"u1"}, false)

Check what relations a target has directly and implicitly (recursive)

The whatCanTargetAccess function is similar to the targetsRelations function in that it takes a single target and returns an array of relations that exist for it, but instead of simply including direct relations, it returns implicit ones as well, traversing the tree of relations recursively.

const target: string = "The target to check relations for directly and implicitly.";


const relations: AuthzRelation[] = descopeClient.management.authz.whatCanTargetAccess(target);

#  Returns the list of all relations for the given target including derived relations from the schema tree.
# Args:
# target (str): the target we are returning the relations for

# Return value (List[dict]):
# Return List of relations each in the format of a relation as documented in create_relations
# Raise:
# AuthException: raised if query fails

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()


_, err = mgmt.Authz().WhatCanTargetAccess(ctx, "u1")


var respWhat = authzService.whatCanTargetAccess("u1");

Check what resources a target can access through a particular relation definition

The whatCanTargetAccessWithRelation function is similar to whatCanTargetAccess, but instead of returning all relations for a given target, it specifically finds resources that the target can access through relation paths ending in a given relation definition.

const target: string = "The target to check relations for directly and implicitly.";


const resources: AuthzResource[] = await descopeClient.management.authz.whatCanTargetAccessWithRelation(
  target,
  relationDefinition,
  namespace,
);

# Returns the list of all resources that the target has the given relation to including all derived relations
# Args:
# target (str): the target we are returning the relations for
# relation_definition (str): the RD we are checking
# namespace (str): the namespace for the RD

# Return value (List[dict]):
# Return List of relations each in the format of a relation as documented in create_relations
# Raise:
# AuthException: raised if query fails

resources = client.management.authz.what_can_target_access_with_relation(
  [
    {
    "target": "u1",
    "relationDefinition": "viewer",
    "namespace": "doc",
    }
  ]
)

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()


_, err = mgmt.Authz().WhatCanTargetAccessWithRelation(ctx, "u1", "rd", "")


var respWhat = authzService.whatCanTargetAccessWithRelation("u1", "rd", "ns");

Get Modified Resources and Targets

The getModified function returns a list of targets and resources that have changed since a given date. This is useful for invalidating local caches and keeping your application's authorization data in sync.

// Get all changes since a specific date
const since = new Date('2024-01-01T00:00:00Z');


const modified = await descopeClient.management.authz.getModified(since);
// Returns: { resources: string[], targets: string[], schemaChanged: boolean }

# Get all targets and resources changed since the given date.
# Args:
# since (datetime): optional, only return changes from this given datetime

# Return value (dict):
# Dict including "resources" list of strings, "targets" list of strings and "schemaChanged" bool
# Raise:
# AuthException: raised if query fails
from datetime import datetime, timezone

since = datetime(2024, 1, 1, tzinfo=timezone.utc)
modified = descope_client.mgmt.authz.get_modified(since)
# Returns: {"resources": ["r1", "r2"], "targets": ["u1", "u2"], "schemaChanged": False}

// Get all changes since a specific date
// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
//    since: time to get changes since (must be within last 24 hours)
ctx := context.Background()

since := time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)

modified, err := descopeClient.Management.Authz().GetModified(ctx, since)
// Returns: &AuthzModified{Resources: []string{"r1", "r2"}, Targets: []string{"u1", "u2"}, SchemaChanged: false}

// Get all changes since a specific date
import java.time.Instant;

Instant since = Instant.parse("2024-01-01T00:00:00Z");

AuthzModified modified = authzService.getModified(since);
// Returns: AuthzModified with resources, targets, and schemaChanged fields

Was this helpful?

On this page