Managing a Schema

Once you've defined your schema, you can implement it in Descope using either the Console or programmatically via SDKs and APIs.

Managing Schemas in the Console

The easiest way to create and manage schemas is through the Descope Console. Navigate to the Authorization page and select the FGA tab.

From the FGA tab, you can:

Create new schemas - Start from scratch or use a template
Edit existing schemas - Modify your schema directly in the editor
Delete schemas - Remove schemas and all associated relations

The Console provides a visual editor where you can write your schema in DSL format, validate it, and save it directly to your project.

Manage Schemas

Managing Schemas with SDKs and APIs

To implement a schema programmatically, you can create a YAML or JSON file that defines the schema and make a saveSchema call via API or SDK. Or, use the other schema management functions to create, update, and delete schemas, namespaces, and relation definitions.

Install SDK

Terminal

npm i --save @descope/node-sdk

Terminal

pip3 install descope

Terminal

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>

Terminal

gem install descope

Import and initialize Management SDK

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 a custom domain within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__', managementKey: managementKey });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

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 a custom domain 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 a custom domain 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'
  }
)

Save (create or update) a schema

The saveSchema function allows for creation or updating of a schema. If the schema already exists, the upgrade parameter determines whether the existing schema will be overwritten entirely.

This code shows how to save the schema defined in a given file (YAML/JSON). An example of this schema file can be found in the Define Schema page.

const schema = `<schema>`;
await descopeClient.management.fga.saveSchema(schema);

# Create or update an FGA schema.
# Args:
# schema (str): the schema in the AuthZ 1.0 DSL
#     model AuthZ 1.0
#     type user
#     type doc
#       relation owner: user
#       relation viewer: user
# Raise:
# AuthException: raised if saving fails
descope_client.mgmt.fga.save_schema(schema)

// 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()

// Save schema
err := descopeClient.Management.FGA().SaveSchema(ctx, schema)

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

String dsl = "model AuthZ 1.0\n" +
             "type user\n" +
             "type document\n" +
             "  relation owner: user\n" +
             "  relation editor: user\n" +
             "  relation viewer: user";

try {
    FGASchema schema = new FGASchema(dsl);
    fs.saveSchema(schema);
} catch (DescopeException de) {
    // Handle the error
}

Delete a schema

The deleteSchema function deletes an existing schema, including all relations.

await descopeClient.management.fga.deleteSchema()

# Note: delete_schema may not be available in the FGA interface
# For schema management, use save_schema to update schemas

// 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.FGA().DeleteSchema(ctx)

// Note: deleteSchema may not be available in the FGA interface
// For schema management, use saveSchema to update schemas

Load a schema

The loadSchema function returns the current project's schema.

// Note: loadSchema may be available through the fga namespace
const schema = await descopeClient.management.fga.loadSchema();

# Note: load_schema may not be available in the FGA interface
# For schema management, use the Console or save_schema to manage schemas

// Load the existing schema
// 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()

schema, err := descopeClient.Management.FGA().LoadSchema(ctx)
if err != nil {
    // handle error
}

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

try {
    FGASchema schema = fs.loadSchema();
    // Do something with schema.getDsl()
} catch (DescopeException de) {
    // Handle the error
}

Dry run a schema

The dryRunSchema function validates a schema without saving it and returns what would be deleted from the current schema. This is useful for testing schema changes before applying them.

// Dry run a schema to see what would be deleted
// 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()

dryRunResponse, err := descopeClient.Management.FGA().DryRunSchema(ctx, schema)
if err != nil {
    // handle error
}

// dryRunResponse contains information about what would be deleted
// This allows you to review changes before applying them

Delete a namespace

The deleteNamespace function deletes a specific namespace and all related relations. This operation cannot be undone.

# Delete a namespace
# Args:
# name (str): namespace name to delete
# schema_name (str): optional, can be used to track the current schema version
# Legacy Authz interface - not recommended for new code
descope_client.mgmt.authz.delete_namespace("doc", schema_name="")

// Delete a namespace
// 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()

// Legacy Authz interface - not recommended for new code
err := descopeClient.Management.Authz().DeleteNamespace(ctx, "doc", "")

Was this helpful?

Ask AI about this page

On this page