Namespaces organize and isolate resources into managed groups, enabling teams to work independently without affecting each other's configurations. Use namespaces to control who can access specific credentials, sources, validators, and notification channels.

How Namespaces Work

Credentials and Channels are root resources—you select a namespace when creating them. All other resources inherit their namespace:

Create a New Namespace

To add a new namespace,

1. Navigate to Workspace > Namespaces.
2. Click + New Namespace.
3. Enter a Name for your namespace.
4. (Optional) Upload an avatar.
5. From the list,
   • Select the relevant members, teams, and API keys to assign to the namespace. You will see a summary of your selection below the table.
   • Select the relevant role to assign to each member, team, and API Key you add to the namespace.
6. Click Create Namespace to finish.

Delete a Namespace

To delete a namespace,

1. Navigate to Workspace > Namespaces.
2. Click the ⋮ menu at the end of the row for the relevant namespace.
3. Select Delete.

If the selected namespace is connected to credentials or channels, you will not be able to delete the namespace until you delete each connected resource. You will see an error message listing the connected resources to delete.

Add API Keys to a Namespace

When you create an API key using the UI, you will need to manually add the API key to each namespace that it needs to access. For more information, see Managing API Keys.

To add API keys to a namespace in the UI,

1. Navigate to Workspace > Namespaces.
2. Select the Namespace you want to add the API key to (create a new namespace).
3. Under Add members, teams, or API keys, scroll down to API Keys.
4. Check the API Keys you want to add to the Namespace and select which role it should have.
5. Click Update (or Create namespace).

Best Practices

The following sections provide guidelines and examples for organizing, assigning access, and choosing roles for your namespaces and namespace members.

Namespace Structure

Choose a namespace structure that reflects how your organization manages data ownership and access:

Assigning Access

Namespaces assignments determine what you see throughout Validio. When assigning members and API keys to namespaces:

• Use teams over individuals: Assign teams to namespaces rather than individual users. This simplifies access management as people join or leave, and team role assignments are automatically inherited by all members.
• Follow least-privilege: Start with Viewer access and grant Editor or Admin only as needed. Consider custom namespace roles for more granular control.
• Dedicated API keys per namespace: Create separate API keys for each namespace rather than sharing one key across multiple namespaces. This makes it easier to rotate keys and audit access.
• Match IaC keys to namespaces: If you manage resources via Infrastructure as Code, create a dedicated API key for each namespace and store it with your IaC configuration.

For more information on how roles and permissions work with namespaces, see About Validio RBAC.

Choosing Roles

Validio provides system roles (Admin, Editor, Viewer) and supports custom roles for granular access control. Custom namespace roles allow you to follow the principle of least privilege. For example, create an "Incident Manager" role with WRITE access only to Incidents, enabling users to triage issues without modifying validator configurations.

Users can have multiple role assignments—direct namespace roles and roles inherited through team membership. When permissions conflict, Validio merges them and applies the highest access level for each resource. Keep this in mind when:

• A user belongs to multiple teams with different namespace roles
• You assign both direct and team-based access to the same namespace

For more information on creating custom roles, see Managing Roles.