---
type: Operations Guide
title: Manage Namespaces
description: The namespace feature is currently in Public Preview. The feature and related documentation are subject to change.
resource: https://scalardl.scalar-labs.com/docs/latest/manage-namespaces/
tags:
- scalardl
- v3.14
- phase:operate
- edition:community
- edition:enterprise
status: stable
product: scalardl
product_title: ScalarDL
version: '3.14'
patch_version: 3.14.0
doc_id: manage-namespaces
lifecycle_phase: operate
editions:
- Community
- Enterprise
generated:
  by: process:okf-build/1.0.0
  at: '2026-08-10T20:40:01Z'
sources:
- id: docs-scalardl
  resource: https://github.com/scalar-labs/docs-scalardl/blob/03da04b21c1a7ce3eb94d9e29129a0ce194ecbeb/docs/manage-namespaces.mdx
  title: ScalarDL documentation source (MDX)
  author: process:scalar-labs/docs-scalardl
  last_modified: '2026-08-07T17:27:19Z'
---

# Manage Namespaces

:::warning

The namespace feature is currently in Public Preview. The feature and related documentation are subject to change.

:::

This document explains how to use namespaces to organize and isolate assets in ScalarDL.

## Overview

Namespaces allow you to logically group and isolate resources within a Ledger. Each namespace contains its own set of:

- **Assets:** The immutable, tamper-evident data stored in the ledger.
- **Credentials:** Certificates or secret keys used for authentication.
- **Contracts:** The business logic that manages assets in the ledger.
- **Functions:** The business logic that works with contracts to manage mutable records in an external database.

By default, all resources are stored in a namespace called `default`. You can create additional namespaces to separate resources for different use cases, such as multi-tenancy, data lifecycle management, or cost optimization.

There are two access models for namespaces:

- **Cross-namespace access model:** A single application accesses assets across multiple namespaces.
- **Restricted access model:** Multiple independent applications each have exclusive access to assets within their own namespace.

## Cross-namespace access model

The cross-namespace access model is suitable for use cases such as the following:

- **Efficient data lifecycle management:** Separate data into namespaces by time period (for example, 1 year), and then bulk-delete data by namespace after the legally required retention period (for example, 10 years) has passed.
- **Cost optimization through storage tiering:** Prepare namespaces on multiple storage systems with different performance characteristics and costs, and store data in different namespaces based on access frequency and importance.

To perform cross-namespace data access, implement contracts by using namespace-aware interfaces and register those contracts in the `default` namespace. Contracts registered in the `default` namespace have a global access scope, allowing them to get, put, and scan assets in any namespace.

For details on developing namespace-aware contracts, see [Manage assets with a namespace](./how-to-write-contract.md#manage-assets-with-a-namespace).

## Restricted access model

The restricted access model is suitable for use cases such as the following:

- **SaaS applications:** Host multiple customers running the same application on a shared ScalarDL cluster while ensuring each customer's data and contracts are completely isolated from one another.
- **Infrastructure consolidation:** Run multiple independent applications from different departments or business units on a single cluster, reducing infrastructure costs while maintaining secure isolation between each application's data and contracts.

ScalarDL supports these scenarios by restricting access to each namespace so that it is independently managed and inaccessible from other namespaces. To set up a namespace with restricted access, first create a namespace, and then register the certificates or secrets of tenant clients that will use each namespace. Then, register contracts and functions for their application through the registered clients. Only clients registered in a namespace can register and execute contracts and functions or validate assets within that namespace.

Unlike contracts registered in the `default` namespace, contracts registered in namespaces with restricted access have only a local access scope and cannot access assets in other namespaces. Likewise, functions registered in namespaces with restricted access can only access the ScalarDB namespace that has the same name as their namespace or a namespace whose name starts with their namespace followed by an underscore, and cannot access any other namespace.

For details on how to set up namespaces and access them in a restricted manner, see [Access Namespaces in a Restricted Manner](./access-namespaces-in-a-restricted-manner.md).

## See also

- [A Guide on How to Write a Good Contract](./how-to-write-contract.md)
- [Access Namespaces in a Restricted Manner](./access-namespaces-in-a-restricted-manner.md)
- [ScalarDL Client Command Reference](./scalardl-command-reference.md)
