Create relations

Once you've created your relation definitions, you can start creating relations between resources and targets. Then, you can finally add the access control checks to your application. We'll start with looking at the relavent objects used in creation and checking of relations.

Understanding the Data Types

When creating a relation, we have the AuthzRelation type which defines a relation between a resource and a target.

type AuthzRelation = {
  resource: string;
  relationDefinition: string;
  namespace: string;
  target?: string;
  targetSetResource?: string;
  targetSetRelationDefinition?: string;
  targetSetRelationDefinitionNamespace?: string;
  query?: AuthzUserQuery;
};

When checking to see if a relation exists, one of the options involves the AuthzRelationQuery type which is used to query the service to see if a given relation exists. The function that takes this object in will return it with the hasRelation boolean field set to true or false depending on whether the relation exists or not.

Other functions include the ability to check what relations exist for a given resource or target.

type AuthzRelationQuery = {
  resource: string;
  relationDefinition: string;
  namespace: string;
  target: string;
  hasRelation?: boolean;
};

Creating, Updating, and Deleting Relations

Install SDK

NodeJSPythonGoJavaRuby

npm i --save @descope/node-sdk

pip3 install descope

go get github.com/descope/go-sdk

// Include the following in your `pom.xml` (for Maven)
<dependency>
    <artifactId>java-sdk</artifactId>
    <groupId>com.descope</groupId>
    <version>sdk-version</version> // Check https://github.com/descope/descope-java/releases for the latest versions
</dependency>

gem install descope

Import and initialize Management SDK

NodeJSPythonGoJavaRuby

import DescopeClient from '@descope/node-sdk';

const managementKey = "xxxx"

try{
    //  baseUrl="<URL>" // When initializing the Descope clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__', managementKey: managementKey });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

from descope import (
    REFRESH_SESSION_TOKEN_NAME,
    SESSION_TOKEN_NAME,
    AuthException,
    DeliveryMethod,
    DescopeClient,
    AssociatedTenant,
    RoleMapping,
    AttributeMapping
)

management_key = "xxxx"

try:
    # You can configure the baseURL by setting the env variable Ex: export DESCOPE_BASE_URI="https://auth.company.com  - this is useful when you utilize CNAME within your Descope project."
    descope_client = DescopeClient(project_id='__ProjectID__', management_key=management_key)
except Exception as error:
    # handle the error
    print ("failed to initialize. Error:")
    print (error)

import "github.com/descope/go-sdk/descope"
import "github.com/descope/go-sdk/descope/client"
import "fmt"

// Utilizing the context package allows 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.
import (
	"context"
)

managementKey = "xxxx"

// DescopeBaseURL // within the client.Config, you can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
descopeClient, err := client.NewWithConfig(&client.Config{ProjectID:"__ProjectID__", managementKey:managementKey})
if err != nil {
    // handle the error
    log.Println("failed to initialize: " + err.Error())
}

import com.descope.client;

// Initialized after setting the DESCOPE_PROJECT_ID env var (and optionally DESCOPE_MANAGEMENT_KEY)
var descopeClient = new DescopeClient();

// ** Or directly **
var descopeClient = new DescopeClient(Config.builder()
        .projectId("__ProjectID__")
        .managementKey("management-key")
        .build());

require 'descope'


descope_client = Descope::Client.new(
  {
    project_id: '__ProjectID__',
    management_key: 'management_key'
  }
)

Create given relations

The createRelations function creates a given array of relations.

NodeJSPythonGoJava

const relations: AuthzRelation[] = [{
        resource: 'some-doc',
        relationDefinition: 'owner',
        namespace: 'doc',
        target: 'u1',
    },
    {
        resource: 'some-doc',
        relationDefinition: 'editor',
        namespace: 'doc',
        target: 'u2',
},];

await descopeClient.management.authz.createRelations(relations);

# Create a relation between a resource and user
descope_client.mgmt.authz.create_relations(
    [
        {
            "resource": "some-doc",
            "relationDefinition": "owner",
            "namespace": "doc",
            "target": "u1",
        }
    ]
)

// 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 := descopeClient.Management.Authz().CreateRelations(ctx, []*descope.AuthzRelation {
    {
        resource: "some-doc",
        relationDefinition: "owner",
        namespace: "doc",
        target: "u1",
    },
})

authzService.createRelations(List.of(
  new Relation("Dev", "parent", "org", "Descope", null, null, null, null),
  new Relation("Sales", "parent", "org", "Descope", null, null, null, null),
));

Delete given relations

The deleteRelations function deletes a given array of relations.

NodeJSPythonGoJava

const relations: AuthzRelations = [{
    resource: 'some-doc',
    relationDefinition: 'owner',
    namespace: 'doc',
    target: 'u1',
},];

await descopeClient.management.authz.deleteRelations(relations);

descope_client.mgmt.authz.delete_relations(
    [
        {
            "resource": "some-doc",
            "relationDefinition": "owner",
            "namespace": "doc",
            "target": "u1",
        }
    ]
)

// 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().DeleteRelations(ctx, []*descope.AuthzRelation{{Resource: "r", RelationDefinition: "rd", Namespace: "ns", Target: "t"}})

authzService.deleteRelations(List.of(
  new Relation("Dev", "parent", "org", "Descope", null, null, null, null),
  new Relation("Sales", "parent", "org", "Descope", null, null, null, null),
));

Delete all relations for given resources

The deleteRelationsForResources function takes an array of resources and deletes all relations for those resources.

NodeJSGoJavaPython

const resources: string[] = [];

await descopeClient.management.authz.deleteRelationsForResources(resources);

// 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().DeleteRelationsForResources(ctx, []string{"1"})

authzService.deleteRelationsForResources(List.of("kuku"));

#  Delete all relations to the given resources
# Args:
# resources (List[str]): the list of resources to delete any relations for
# Raise:
# AuthException: raised if delete relations for resources fails
client.mgmt.authz.delete_relations_for_resources(["r"])

We'll move on to checking relations.

Was this article helpful?Yes No