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, select FGA, and open the Schema tab.

From the Schema 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 code editor where you can write your schema in DSL format, validate it, and save it directly to your project.

Visualizing Your Schema

Alongside the editor, the Schema tab includes a graphs panel with two views:

Relations Graph - Shows how relations connect your types
Permission Graphs - Shows how relations resolve into your permissions

Schema Graphs

The permission graph merges relation leaves that feed the same permissions in the exact same way into a single node, so the graph stays readable even when several relations grant identical access.

The graphs reflect your last saved schema, not unsaved edits in the editor:

Unsaved changes show a placeholder in both graphs until you save
A schema with no permissions defined shows a placeholder on the Permission Graphs view instead of an empty graph
Narrower screens hide the graphs panel so the editor has room to work

Viewing schema graphs

Next to the schema editor, the Relations Graph and Permission Graphs tabs visualize your saved schema as diagrams. Unsaved edits in the editor clear these diagrams until you save again.

Each rendered graph has a copy button in its top-right corner. Clicking it copies the graph's underlying Mermaid source code to your clipboard, letting you reuse the diagram elsewhere, such as in your own documentation or an external Mermaid editor. The button appears only alongside a rendered graph, so it's absent while edits are unsaved, and on the Permission Graphs tab if the schema defines no permissions.

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?

On this page