> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validio.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Namespaces

> Organize and isolate Validio resources into managed groups, and target them from the Validio API, SDK, and CLI.

Namespaces organize and isolate resources into managed groups. Resources created in one namespace are only visible and accessible within that namespace, so teams can work independently without affecting each other's configurations.

Common use cases:

* **Team separation:** Give each team its own namespace to manage their sources and validators independently.
* **Environment isolation:** Use separate namespaces for development, staging, and production.
* **IaC management:** Assign a dedicated namespace to resources deployed through Infrastructure-as-Code to prevent conflicts with manually created resources.

For information on creating and managing namespaces in the UI, see [Managing namespaces](https://docs.validio.io/v10.3/docs/access-and-settings/settings/managing-namespaces.md).

## Specify a namespace

When using the CLI or SDK, you can target a specific namespace in two ways:

1. **Per request:** Pass the `-n` or `--namespace` flag with CLI commands, or include the namespace in your API request.
2. **Default namespace:** Configure a default using `validio config ns <namespace>` (CLI) or set `default_namespace` in your `ValidioConfig` (SDK).

## Manage namespaces with the CLI

Create a namespace and assign members or API keys with roles:

```bash title="Bash" theme={null}
# Create a namespace and add a member as Admin
validio namespaces create my-namespace [--role ADMIN --member <user-uuid>]

# Add an API key to an existing namespace as Viewer
validio namespaces update my-namespace [--role VIEWER --api-key <key-id>]
```

> [!NOTE]
>
> The API key that is used when creating the namespace is added as `ADMIN` by default.

## API keys and namespaces

An API key has a global role, similar to the global role for users, that determines access rights for non-namespaced resources such as users, namespaces, and tags.

How an API key gains access to a namespace depends on where the namespace was created:

* **Created with the CLI:** If an API key has the global role `Admin` and you use it with the Validio CLI to create a namespace, that API key is automatically added to the namespace with the `Admin` role.
* **Created in the UI:** If you create an API key in the UI, you must manually add it to each namespace that it needs to access. See [Add API keys to a namespace](https://docs.validio.io/v10.3/docs/access-and-settings/settings/managing-namespaces.md#add-api-keys-to-a-namespace).

## The default namespace

Resources created in the Validio UI are assigned to the namespace `default`. To avoid conflicts, don't use this namespace in your [Validio Code (IaC)](https://docs.validio.io/v10.3/developer/validio-code.md) projects. To bring resources created in the UI under IaC management, import them out of `default` instead. See [Import resources](https://docs.validio.io/v10.3/developer/validio-code/scenarios.md#import-resources).