Manage roles
In Weaviate, Role-based access control (RBAC) allows you to define roles and assign permissions to those roles. Users can then be assigned to roles and inherit the permissions associated with those roles.
On this page, you will find examples of how to manage roles and permissions with Weaviate client libraries.
Step 1. Connect to Weaviate with a user possessing
role management permissions
.
Step 2. Grant permissions to a
new role
or an
existing role
.
- Step 3.
Assign the role to a user
.
Requirements for managing roles
Role management requires appropriate role resource permissions that can be obtained through:
- A predefined
rootrole when configuring RBAC. - A role with
Role Managementpermissions granted.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
import weaviate
from weaviate.classes.init import Auth
# Connect to Weaviate as root user
client = weaviate.connect_to_local(
auth_credentials=Auth.api_key("root-user-key"),
)
import weaviate, { WeaviateClient } from '@weaviate/node'
// Connect to Weaviate as root user
const client: WeaviateClient = await weaviate.connectToLocal({
authCredentials: new weaviate.ApiKey("user-a-key")
})
cfg := weaviate.Config{
Host: "localhost:8580",
Scheme: "http",
AuthConfig: auth.ApiKey{Value: "root-user-key"},
}
// Connect to Weaviate as root user
client, err := weaviate.NewClient(cfg)
// Connect to Weaviate as root user
client, err := weaviate.NewLocal(ctx,
weaviate.WithAPIKey("root-user-key"),
)
if err != nil {
// handle error
panic(err)
}
defer client.Close()
// Connect to Weaviate as root user
client = WeaviateClient.connectToLocal(config -> config
.authentication(Authentication.apiKey("root-user-key")));
// Connect to Weaviate as root user
client = await Connect.Local(restPort: 8580, grpcPort: 50551, credentials: RootUserKey);
Role management
Create new roles with permissions
Permissions for these resource types can be assigned to roles:
-
Collections (collection definitions only, data object permissions are separate)
Create a role with Role Management permissions
This example creates a role called testRole with permissions to:
- Create, read, update and delete all roles starting with
testRole*.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions, RoleScope
permissions = [
Permissions.roles(
role="testRole*", # Applies to all roles starting with "testRole"
scope=RoleScope.MATCH, # Only allow role management with the current user's permission level
# scope=RoleScope.ALL # Allow role management with all permissions
create=True, # Allow creating roles
read=True, # Allow reading roles
update=True, # Allow updating roles
delete=True, # Allow deleting roles
)
]
client.roles.create(role_name="testRole", permissions=permissions)
const { permissions } = weaviate
const rolePermission = permissions.roles({
role: "testRole",
create: true,
read: true,
update: true,
delete: true,
})
await client.roles.create("testRole", rolePermission)
permissions := []rbac.Permission{
rbac.RolesPermission{
Role: "testRole*", // Applies to all roles starting with "testRole"
Scope: "match", // Only allow role management with the current user's permission level, can also be "all"
// Scope: rbac.RoleScopeAll, // Allow role management with all permissions
Actions: []string{
models.PermissionActionCreateRoles, // Allow creating roles
models.PermissionActionReadRoles, // Allow reading roles
models.PermissionActionUpdateRoles, // Allow updating roles
models.PermissionActionDeleteRoles, // Allow deleting roles
},
},
}
err = client.Roles().Creator().WithRole(rbac.NewRole("testRole", permissions...)).Do(ctx)
// Coming soon
Permission[] rolesPermissions =
new Permission[] {Permission.roles("testRole*", // Applies to all roles starting with "testRole"
RolesPermission.Scope.MATCH, // Only allow role management with the current user's permission level
// RolesPermission.Scope.ALL, // Allow role management with all permissions
RolesPermission.Action.CREATE, // Allow creating roles
RolesPermission.Action.READ, // Allow reading roles
RolesPermission.Action.UPDATE, // Allow updating roles
RolesPermission.Action.DELETE // Allow deleting roles
)};
client.roles.create("testRole_ManageRoles", rolesPermissions);
var rolesPermissions = new PermissionScope[]
{
new Permissions.Roles("testRole*", RolesScope.Match) // Only allow role management with the current user's permission level
{
Create = true, // Allow creating roles
Read = true, // Allow reading roles
Update = true, // Allow updating roles
Delete = true, // Allow deleting roles
},
};
await client.Roles.Create("testRole_ManageRoles", rolesPermissions);
Create a role with User Management permissions
This example creates a role called testRole with permissions to:
- Create, read, update and delete all users starting with
testUser*. - Assign and revoke roles to and from users starting with
testUser*.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.users(
user="testUser*", # Applies to all users starting with "testUser"
create=True, # Allow creating users
read=True, # Allow reading user info
update=True, # Allow rotating user API key
delete=True, # Allow deleting users
assign_and_revoke=True, # Allow assigning and revoking roles to and from users
)
]
client.roles.create(role_name="testRole", permissions=permissions)
const userPermission = permissions.users({
user: "testRole", // Applies to all users starting with "testUser"
assignAndRevoke: true, // Allow assigning and revoking roles to and from users
read: true, // Allow reading user info
})
await client.roles.create("testRole", userPermission)
permissions := []rbac.Permission{
rbac.UsersPermission{
Actions: []string{
models.PermissionActionCreateUsers, // Allow creating users
models.PermissionActionReadUsers, // Allow reading user info
models.PermissionActionUpdateUsers, // Allow rotating user API key
models.PermissionActionDeleteUsers, // Allow deleting users
models.PermissionActionAssignAndRevokeUsers, // Allow assigning and revoking roles to and from users
},
},
}
err = client.Roles().Creator().WithRole(rbac.NewRole("testRole", permissions...)).Do(ctx)
err := client.Roles.Create(ctx, rbac.Role{
ID: "testRole",
Permissions: rbac.Permissions{
Users: []rbac.UserPermission{
{
UserID: "testUser*", // Applies to all users starting with "testUser".
Create: true, // Allow creating users.
Read: true, // Allow reading user info.
Update: true, // Allow rotating a user's API key.
Delete: true, // Allow deleting users.
AssignAndRevoke: true, // Allow assigning and revoking roles.
},
},
},
})
if err != nil {
// handle error
panic(err)
}
Permission[] usersPermissions =
new Permission[] {Permission.users("testUser*", // Applies to all users starting with "testUser"
UsersPermission.Action.CREATE, // Allow creating users
UsersPermission.Action.READ, // Allow reading user info
UsersPermission.Action.UPDATE, // Allow rotating user API key
UsersPermission.Action.DELETE, // Allow deleting users
UsersPermission.Action.ASSIGN_AND_REVOKE // Allow assigning and revoking roles to and from users
)};
client.roles.create("testRole_ManageUsers", usersPermissions);
var usersPermissions = new PermissionScope[]
{
new Permissions.Users("testUser*") // Applies to all users starting with "testUser"
{
Create = true, // Allow creating users
Read = true, // Allow reading user info
Update = true, // Allow rotating user API key
Delete = true, // Allow deleting users
AssignAndRevoke = true, // Allow assigning and revoking roles to and from users
},
};
await client.Roles.Create("testRole_ManageUsers", usersPermissions);
Create a role with Collections permissions
This example creates a role called testRole with permissions to:
- Create, read, update and delete all collections starting with
TargetCollection.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.collections(
collection="TargetCollection*", # Applies to all collections starting with "TargetCollection"
create_collection=True, # Allow creating new collections
read_config=True, # Allow reading collection info/metadata
update_config=True, # Allow updating collection configuration, i.e. update schema properties, when inserting data with new properties
delete_collection=True, # Allow deleting collections
),
]
client.roles.create(role_name="testRole", permissions=permissions)
const { permissions } = weaviate
const collectionPermissions = [
permissions.collections({
collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
create_collection: true, // Allow creating new collections
read_config: true, // Allow reading collection info/metadata
update_config: true, // Allow updating collection configuration, i.e. update schema properties, when inserting data with new properties
delete_collection: true, // Allow deleting collections
}),
]
await client.roles.create("testRole", collectionPermissions)
permissions := []rbac.Permission{
rbac.CollectionsPermission{
Collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
Actions: []string{
models.PermissionActionCreateCollections, // Allow creating new collections
models.PermissionActionReadCollections, // Allow reading collection info/metadata
models.PermissionActionUpdateCollections, // Allow updating collection configuration, i.e. update schema properties, when inserting data with new properties
models.PermissionActionDeleteCollections, // Allow deleting collections
},
},
}
err = client.Roles().Creator().WithRole(rbac.NewRole("testRole", permissions...)).Do(ctx)
err := client.Roles.Create(ctx, rbac.Role{
ID: "testRole",
Permissions: rbac.Permissions{
Collections: []rbac.CollectionPermission{
{
Collection: "TargetCollection*", // Applies to all matching collections.
Create: true, // Allow creating collections.
Read: true, // Allow reading collection config.
Update: true, // Allow updating collection config.
Delete: true, // Allow deleting collections.
},
},
},
})
if err != nil {
// handle error
panic(err)
}
Permission[] collectionsPermissions =
new Permission[] {Permission.collections("TargetCollection*", // Applies to all collections starting with "TargetCollection"
CollectionsPermission.Action.CREATE, // Allow creating new collections
CollectionsPermission.Action.READ, // Allow reading collection info/metadata
CollectionsPermission.Action.UPDATE, // Allow updating collection configuration
CollectionsPermission.Action.DELETE // Allow deleting collections
),};
client.roles.create("testRole_ManageCollections", collectionsPermissions);
var collectionsPermissions = new PermissionScope[]
{
new Permissions.Collections("TargetCollection*") // Applies to all collections starting with "TargetCollection"
{
Create = true, // Allow creating new collections
Read = true, // Allow reading collection info/metadata
Update = true, // Allow updating collection configuration
Delete = true, // Allow deleting collections
},
};
await client.Roles.Create("testRole_ManageCollections", collectionsPermissions);
Create a role with Tenant permissions
This example creates a role called testRole with permissions to:
- Create and delete tenants starting with
TargetTenantin collections starting withTargetCollection. - Read metadata (like tenant names and status) for tenants starting with
TargetTenantin collections starting withTargetCollection. - Update the status of tenants starting with
TargetTenantin collections starting withTargetCollection.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.tenants(
collection="TargetCollection*", # Applies to all collections starting with "TargetCollection"
tenant="TargetTenant*", # Applies to all tenants starting with "TargetTenant"
create=True, # Allow creating new tenants
read=True, # Allow reading tenant info/metadata
update=True, # Allow updating tenant states
delete=True, # Allow deleting tenants
),
]
client.roles.create(role_name="testRole", permissions=permissions)
const { permissions } = weaviate
const AddTenantPermissions = [
permissions.tenants({
collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
tenant: "TargetTenant*", // Applies to all tenants starting with "TargetTenant"
create: true, // Allow creating new tenants
read: true, // Allow reading tenant info/metadata
update: true, // Allow updating tenant states
delete: true, // Allow deleting tenants
}),
]
await client.roles.create("testRole", AddTenantPermissions)
permissions := []rbac.Permission{
rbac.TenantsPermission{
Actions: []string{
models.PermissionActionCreateTenants, // Allow creating new tenants
models.PermissionActionReadTenants, // Allow reading tenant info/metadata
models.PermissionActionUpdateTenants, // Allow updating tenant states
models.PermissionActionDeleteTenants, // Allow deleting tenants
},
},
}
err = client.Roles().Creator().WithRole(rbac.NewRole("testRole", permissions...)).Do(ctx)
err := client.Roles.Create(ctx, rbac.Role{
ID: "testRole",
Permissions: rbac.Permissions{
Tenants: []rbac.TenantPermission{
{
Collection: "TargetCollection*", // Applies to all matching collections.
Tenant: "TargetTenant*", // Applies to all matching tenants.
Create: true, // Allow creating tenants.
Read: true, // Allow reading tenant info.
Update: true, // Allow updating tenant states.
Delete: true, // Allow deleting tenants.
},
},
},
})
if err != nil {
// handle error
panic(err)
}
Permission[] tenantsPermissions =
new Permission[] {Permission.tenants("TargetCollection*", // Applies to all collections starting with "TargetCollection"
"TargetTenant*", // Applies to all tenants starting with "TargetTenant"
TenantsPermission.Action.CREATE, // Allow creating new tenants
TenantsPermission.Action.READ, // Allow reading tenant info/metadata
TenantsPermission.Action.UPDATE, // Allow updating tenant states
TenantsPermission.Action.DELETE // Allow deleting tenants
),};
client.roles.create("testRole_ManageTenants", tenantsPermissions);
var tenantsPermissions = new PermissionScope[]
{
new Permissions.Tenants("TargetCollection*", "TargetTenant*") // Applies to specified collections/tenants
{
Create = true, // Allow creating new tenants
Read = true, // Allow reading tenant info/metadata
Update = true, // Allow updating tenant states
Delete = true, // Allow deleting tenants
},
};
await client.Roles.Create("testRole_ManageTenants", tenantsPermissions);
Create a role with Data Objects permissions
This example creates a role called testRole with permissions to:
- Create, read, update and delete data from collections starting with
TargetCollection. - If multi-tenancy is enabled and the
tenantfilter is set, the permission only applies to tenants starting withTargetTenant.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.data(
collection="TargetCollection*", # Applies to all collections starting with "TargetCollection"
tenant="TargetTenant*", # Applies to all tenants starting with "TargetTenant"
create=True, # Allow data inserts
read=True, # Allow query and fetch operations
update=True, # Allow data updates
delete=False, # Allow data deletes
),
]
client.roles.create(role_name="testRole", permissions=permissions)
const { permissions } = weaviate
const dataPermissions = [
permissions.data({
collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
tenant: "TargetTenant*", // Applies to all tenants starting with "TargetTenant"
create: true, // Allow data inserts
read: true, // Allow query and fetch operations
update: true, // Allow data updates
delete: false, // Allow data deletes
}),
]
await client.roles.create("testRole", dataPermissions)
permissions := []rbac.Permission{
rbac.DataPermission{
Collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
Actions: []string{
models.PermissionActionCreateData, // Allow data inserts
models.PermissionActionReadData, // Allow query and fetch operations
models.PermissionActionUpdateData, // Allow data updates
// models.PermissionActionDeleteData, // Allow data deletes - set to false by not including
},
},
}
err = client.Roles().Creator().WithRole(rbac.NewRole("testRole", permissions...)).Do(ctx)
err := client.Roles.Create(ctx, rbac.Role{
ID: "testRole",
Permissions: rbac.Permissions{
Data: []rbac.DataPermission{
{
Collection: "TargetCollection*", // Applies to all matching collections.
Tenant: "TargetTenant*", // Applies to all matching tenants.
Create: true, // Allow data inserts.
Read: true, // Allow query and fetch operations.
Update: true, // Allow data updates.
// Delete is left false, disallowing data deletes.
},
},
},
})
if err != nil {
// handle error
panic(err)
}
Permission[] dataPermissions =
new Permission[] {Permission.data("TargetCollection*", // Applies to all collections starting with "TargetCollection"
// "TargetTenant*", // Applies to all tenants starting with "TargetTenant"
DataPermission.Action.CREATE, // Allow data inserts
DataPermission.Action.READ, // Allow query and fetch operations
DataPermission.Action.UPDATE, // Allow data updates
DataPermission.Action.DELETE // Allow data deletes (set to false in example)
),};
client.roles.create("testRole_ManageData", dataPermissions);
var dataPermissions = new PermissionScope[]
{
new Permissions.Data("TargetCollection*", "TargetTenant*") // Applies to all collections starting with "TargetCollection"
{
Create = true, // Allow data inserts
Read = true, // Allow query and fetch operations
Update = true, // Allow data updates
Delete = true, // Allow data deletes
},
};
await client.Roles.Create("testRole_ManageData", dataPermissions);
Create a role with Backups permissions
v1.39.10The read_backups action lists backups and reads backup and restore status. It cannot create, restore or cancel a backup. Like manage_backups, it is scoped by collection. The client libraries do not have a helper for it yet. Grant it through the REST API with "action": "read_backups" and a backups resource.
This example creates a role called testRole with permissions to:
- Manage backups for collections starting with
TargetCollection.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.backup(
collection="TargetCollection*", # Applies to all collections starting with "TargetCollection"
manage=True, # Allow managing backups
),
]
client.roles.create(role_name="testRole", permissions=permissions)
const { permissions } = weaviate
const backupsPermissions = [
permissions.backup({
collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
manage: true, // Allow managing backups
}),
]
await client.roles.create("testRole", backupsPermissions)
permissions := []rbac.Permission{
rbac.BackupsPermission{
Collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
Actions: []string{
models.PermissionActionManageBackups, // Allow managing backups
},
},
}
err = client.Roles().Creator().WithRole(rbac.NewRole("testRole", permissions...)).Do(ctx)
err := client.Roles.Create(ctx, rbac.Role{
ID: "testRole",
Permissions: rbac.Permissions{
Backups: []rbac.BackupsPermission{
{
Collection: "TargetCollection*", // Applies to all matching collections.
Manage: true, // Allow managing backups.
},
},
},
})
if err != nil {
// handle error
panic(err)
}
Permission[] backupPermissions =
new Permission[] {Permission.backups("TargetCollection*", // Applies to all collections starting with "TargetCollection"
BackupsPermission.Action.MANAGE // Allow managing backups
),};
client.roles.create("testRole_ManageBackups", backupPermissions);
var backupPermissions = new PermissionScope[]
{
new Permissions.Backups("TargetCollection*") // Applies to all collections starting with "TargetCollection"
{
Manage = true, // Allow managing backups
},
};
await client.Roles.Create("testRole_ManageBackups", backupPermissions);
Create a role with Cluster Data Access permissions
This example creates a role called testRole with permissions to:
- Read cluster metadata.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.cluster(read=True), # Allow reading cluster data
]
client.roles.create(role_name="testRole", permissions=permissions)
const { permissions } = weaviate
const clusterPermissions = [
permissions.cluster({
read: true // Allow reading cluster data
}),
]
await client.roles.create("testRole", clusterPermissions)
permissions := []rbac.Permission{
rbac.ClusterPermission{
Actions: []string{
models.PermissionActionReadCluster, // Allow reading cluster data
},
},
}
err = client.Roles().Creator().WithRole(rbac.NewRole("testRole", permissions...)).Do(ctx)
err := client.Roles.Create(ctx, rbac.Role{
ID: "testRole",
Permissions: rbac.Permissions{
Cluster: []rbac.ClusterPermission{
{Read: true}, // Allow reading cluster data.
},
},
})
if err != nil {
// handle error
panic(err)
}
Permission[] clusterPermissions =
new Permission[] {Permission.cluster(ClusterPermission.Action.READ), // Allow reading cluster data
};
client.roles.create("testRole_ReadCluster", clusterPermissions);
var clusterPermissions = new PermissionScope[]
{
new Permissions.Cluster { Read = true }, // Allow reading cluster data
};
await client.Roles.Create("testRole_ReadCluster", clusterPermissions);
Create a role with Node Data Access permissions
This example creates a role called testRole with permissions to:
- Read node metadata at the specified verbosity level for collections starting with
TargetCollection.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
verbose_permissions = [
Permissions.Nodes.verbose(
collection="TargetCollection*", # Applies to all collections starting with "TargetCollection"
read=True, # Allow reading node metadata
),
]
# The `minimal` verbosity level applies to all collections unlike
# the `verbose` level where you specify the collection name filter
minimal_permissions = [
Permissions.Nodes.minimal(
read=True, # Allow reading node metadata
),
]
client.roles.create(
role_name="testRole", permissions=verbose_permissions
) # or `minimal_permissions`
const { permissions } = weaviate
const verboseNodePermissions = [
permissions.nodes.verbose({
collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
read: true, // Allow reading node metadata
}),
]
// The `minimal` verbosity level applies to all collections unlike
// the `verbose` level where you specify the collection name filter
const minimalNodePermissions = [
permissions.nodes.minimal({
read: true, // Allow reading node metadata
}),
]
await client.roles.create("testRole", verboseNodePermissions) // or `minimalNodePermissions`
verbosePermissions := []rbac.Permission{
rbac.NodesPermission{
Verbosity: "verbose",
Collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
Actions: []string{
models.PermissionActionReadNodes, // Allow reading node metadata
},
},
}
// The `minimal` verbosity level applies to all collections unlike
// the `verbose` level where you specify the collection name filter
err = client.Roles().Creator().WithRole(
rbac.NewRole("testRole", verbosePermissions...),
).Do(ctx)
// Coming soon
Permission[] verbosePermissions =
new Permission[] {Permission.nodes("TargetCollection*", // Applies to all collections starting with "TargetCollection"
NodesPermission.Action.READ // Allow reading node metadata
),};
// The `minimal` verbosity level is not exposed, use the standard one
// which corresponds to 'verbose'
client.roles.create("testRole_ReadNodes", verbosePermissions);
var verbosePermissions = new PermissionScope[]
{
new Permissions.Nodes("TargetCollection*", NodeVerbosity.Verbose) // Applies to all collections starting with "TargetCollection"
{
Read = true, // Allow reading node metadata
},
};
await client.Roles.Create("testRole_ReadNodes", verbosePermissions);
Create a role with Collection Alias permissions
This example creates a role called testRole with permissions to:
- Create, read, update and delete collection aliases starting with
TargetAlias.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.alias(
alias="TargetAlias*", # Applies to all aliases starting with "TargetAlias"
collection="TargetCollection*", # Applies to all collections starting with "TargetCollection"
create=True, # Allow alias creation
read=True, # Allow listing aliases
update=True, # Allow updating aliases
delete=False, # Allow deleting aliases
),
]
client.roles.create(role_name="testRole", permissions=permissions)
const aliasPermissions = [
permissions.aliases({
alias: "TargetAlias*", // Applies to all aliases starting with "TargetAlias"
collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
create: true, // Allow alias creation
read: true, // Allow listing aliases
update: true, // Allow updating aliases
delete: false, // Allow deleting aliases
}),
]
await client.roles.create("testRole", aliasPermissions)
permissions := []rbac.Permission{
rbac.AliasPermission{
Alias: "TargetAlias*", // Applies to all aliases starting with "TargetAlias"
Collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
Actions: []string{
models.PermissionActionCreateAliases, // Allow alias creation
models.PermissionActionReadAliases, // Allow listing aliases
models.PermissionActionUpdateAliases, // Allow updating aliases
// models.PermissionActionDeleteAliases, // Allow deleting aliases - set to false by not including
},
},
}
err = client.Roles().Creator().WithRole(rbac.NewRole("testRole", permissions...)).Do(ctx)
err := client.Roles.Create(ctx, rbac.Role{
ID: "testRole",
Permissions: rbac.Permissions{
Aliases: []rbac.AliasPermission{
{
Alias: "TargetAlias*", // Applies to all matching aliases.
Collection: "TargetCollection*", // Applies to all matching collections.
Create: true, // Allow alias creation.
Read: true, // Allow listing aliases.
Update: true, // Allow updating aliases.
// Delete is left false, disallowing alias deletion.
},
},
},
})
if err != nil {
// handle error
panic(err)
}
Permission[] aliasPermissions =
new Permission[] {Permission.aliases("TargetAlias*", // Applies to all aliases starting with "TargetAlias"
"TargetCollection*", // Applies to all collections starting with "TargetCollection"
AliasesPermission.Action.CREATE, // Allow alias creation
AliasesPermission.Action.READ, // Allow listing aliases
AliasesPermission.Action.UPDATE // Allow updating aliases
// Delete is false in example
),};
client.roles.create("testRole_ManageAliases", aliasPermissions);
var aliasPermissions = new PermissionScope[]
{
new Permissions.Alias("TargetCollection*", "TargetAlias*")
{
Create = true, // Allow alias creation
Read = true, // Allow listing aliases
Update = true, // Allow updating aliases
// Delete is false by default
},
};
await client.Roles.Create("testRole_ManageAliases", aliasPermissions);
Create a role with Replications permissions
This example creates a role called testRole with permissions to:
- Create, read, update and delete replica movement operations for collections starting with
TargetCollectionand shards starting withTargetShard.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.replicate(
collection="TargetCollection*", # Applies to all collections starting with "TargetCollection"
shard="TargetShard*", # Applies to all shards starting with "TargetShard"
create=True, # Allow replica movement operations
read=True, # Allow retrieving replication status
update=True, # Allow cancelling replication operations
delete=False, # Allow deleting replication operations
),
]
client.roles.create(role_name="testRole", permissions=permissions)
// TS/JS support coming soon
permissions := []rbac.Permission{
rbac.ReplicatePermission{
Collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
Shard: "TargetShard*", // Applies to all shards starting with "TargetShard"
Actions: []string{
models.PermissionActionCreateReplicate, // Allow replica movement operations
models.PermissionActionReadReplicate, // Allow retrieving replication status
models.PermissionActionUpdateReplicate, // Allow cancelling replication operations
// models.PermissionActionDeleteReplicate, // Allow deleting replication operations - set to false by not including
},
},
}
err = client.Roles().Creator().WithRole(rbac.NewRole("testRole", permissions...)).Do(ctx)
err := client.Roles.Create(ctx, rbac.Role{
ID: "testRole",
Permissions: rbac.Permissions{
Replication: []rbac.ReplicationPermission{
{
Collection: "TargetCollection*", // Applies to all matching collections.
Shard: "TargetShard*", // Applies to all matching shards.
Create: true, // Allow replica movement operations.
Read: true, // Allow retrieving replication status.
Update: true, // Allow cancelling replication operations.
// Delete is left false, disallowing deleting replication operations.
},
},
},
})
if err != nil {
// handle error
panic(err)
}
Permission[] replicatePermissions =
new Permission[] {Permission.replicate("TargetCollection*", // Applies to all collections starting with "TargetCollection"
"TargetShard*", // Applies to all shards starting with "TargetShard"
ReplicatePermission.Action.CREATE, // Allow replica movement operations
ReplicatePermission.Action.READ, // Allow retrieving replication status
ReplicatePermission.Action.UPDATE // Allow cancelling replication operations
// Delete is false in example
),};
client.roles.create("testRole_ManageReplicas", replicatePermissions);
var replicatePermissions = new PermissionScope[]
{
new Permissions.Replicate("TargetCollection*", "TargetShard*")
{
Create = true, // Allow replica movement operations
Read = true, // Allow retrieving replication status
Update = true, // Allow cancelling replication operations
// Delete is false by default
},
};
await client.Roles.Create("testRole_ManageReplicas", replicatePermissions);
Create a role with Groups permissions
This example creates a role called testRole with permissions to:
- Read information about and assign/revoke group membership for OIDC groups starting with
TargetGroup.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.Groups.oidc(
group="TargetGroup*", # Applies to all groups starting with "TargetGroup"
read=True, # Allow reading group information
assign_and_revoke=True, # Allow assigning and revoking group memberships
),
]
client.roles.create(role_name="testRole", permissions=permissions)
// TS/JS support coming soon
// Coming soon
// permissions := []rbac.Permission{
// rbac.GroupsPermission{
// Group: "TargetGroup*", // Applies to all groups starting with "TargetGroup"
// Actions: []string{
// models.PermissionActionReadGroups, // Allow reading group information
// models.PermissionActionAssignAndRevokeGroups, // Allow assigning and revoking group memberships
// },
// },
// }
// err = client.Roles().Creator().WithRole(rbac.NewRole("testRole", permissions...)).Do(ctx)
err := client.Roles.Create(ctx, rbac.Role{
ID: "testRole",
Permissions: rbac.Permissions{
Groups: []rbac.GroupPermission{
{
GroupID: "TargetGroup*", // Applies to all groups starting with "TargetGroup".
Type: rbac.GroupTypeOIDC,
Read: true, // Allow reading group information.
AssignAndRevoke: true, // Allow assigning and revoking group memberships.
},
},
},
})
if err != nil {
// handle error
panic(err)
}
Permission[] groupsPermissions =
new Permission[] {Permission.groups("TargetGroup*", // Applies to all groups starting with "TargetGroup"
GroupType.OIDC, GroupsPermission.Action.READ, // Allow reading group information
GroupsPermission.Action.ASSIGN_AND_REVOKE // Allow assigning and revoking group memberships
),};
client.roles.create("testRole_ManageGroups", groupsPermissions);
var groupsPermissions = new PermissionScope[]
{
new Permissions.Groups("TargetGroup*", RbacGroupType.Oidc)
{
Read = true, // Allow reading group information
AssignAndRevoke = true, // Allow assigning and revoking group memberships
},
};
await client.Roles.Create("testRole_ManageGroups", groupsPermissions);
Create a role with MCP permissions
The Weaviate MCP server uses three granular permissions:
| Permission | Tools |
|---|---|
read_mcp | weaviate-collections-get-config, weaviate-tenants-list, weaviate-query-hybrid |
create_mcp + update_mcp | weaviate-objects-upsert |
MCP tools also require standard collection-level permissions (e.g., read_data for search, create_data + update_data for upsert). See the MCP server permissions for the full per-tool breakdown.
Grant additional permissions
Additional permissions can be granted to a role at any time. The role must already exist.
This example grants additional permissions to the role testRole to:
- Create new data in collections that start with
TargetCollection
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.data(collection="TargetCollection*", create=True),
]
client.roles.add_permissions(permissions=permissions, role_name="testRole")
const { permissions } = weaviate
const additionalDataPermissions = [
permissions.data({
collection: "TargetCollection*",
read: true,
create: true
}),
permissions.data({
collection: "TargetCollection*",
read: true,
create: false
}),
]
client.roles.addPermissions("testRole", additionalDataPermissions)
permissions := []rbac.Permission{
rbac.DataPermission{
Collection: "TargetCollection*",
Actions: []string{
models.PermissionActionCreateData,
},
},
}
err = client.Roles().PermissionAdder().
WithRole("testRole").
WithPermissions(permissions...).
Do(ctx)
err := client.Roles.AddPermissions(ctx, rbac.AddPermissions{
RoleID: "testRole",
Permissions: rbac.Permissions{
Data: []rbac.DataPermission{
{Collection: "TargetCollection*", Create: true},
},
},
})
if err != nil {
// handle error
panic(err)
}
Permission[] additionalPermissions = new Permission[] {
Permission.data("TargetCollection*", DataPermission.Action.CREATE)};
client.roles.addPermissions(testRole, additionalPermissions);
var additionalPermissions = new PermissionScope[]
{
new Permissions.Data("TargetCollection*", "TargetTenant*") { Create = true },
};
await client.Roles.AddPermissions(testRole, additionalPermissions);
Remove permissions from a role
Permissions can be revoked from a role at any time. Removing all permissions from a role will delete the role itself.
This example removes the following permissions from the role testRole:
- Read the data from collections that start with
TargetCollection - Create and delete collections that start with
TargetCollection
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.collections(
collection="TargetCollection*",
read_config=True,
create_collection=True,
delete_collection=True,
),
Permissions.data(collection="TargetCollection*", read=True, create=False),
]
client.roles.remove_permissions(role_name="testRole", permissions=permissions)
const { permissions } = weaviate
const permissionsToRemove = [
permissions.collections({
collection: "TargetCollection*",
read_config: true,
create_collection: true,
delete_collection: true,
}),
permissions.data({
collection: "TargetCollection*",
read: true,
create: false
}),
]
await client.roles.removePermissions("testRole", permissionsToRemove)
permissions = []rbac.Permission{
rbac.CollectionsPermission{
Collection: "TargetCollection*",
Actions: []string{
models.PermissionActionReadCollections,
models.PermissionActionCreateCollections,
models.PermissionActionDeleteCollections,
},
},
rbac.DataPermission{
Collection: "TargetCollection*",
Actions: []string{
models.PermissionActionReadData,
// models.PermissionActionCreateData, // create=False
},
},
}
err = client.Roles().PermissionRemover().
WithRole("testRole").
WithPermissions(permissions...).
Do(ctx)
err := client.Roles.RemovePermissions(ctx, rbac.RemovePermissions{
RoleID: "testRole",
Permissions: rbac.Permissions{
Collections: []rbac.CollectionPermission{
{Collection: "TargetCollection*", Read: true, Create: true, Delete: true},
},
Data: []rbac.DataPermission{
{Collection: "TargetCollection*", Read: true},
},
},
})
if err != nil {
// handle error
panic(err)
}
Permission[] permissionsToRemove = new Permission[] {
Permission.collections("TargetCollection*",
CollectionsPermission.Action.READ),
Permission.data("TargetCollection*", DataPermission.Action.CREATE),};
client.roles.removePermissions(testRole, permissionsToRemove);
var permissionsToRemove = new PermissionScope[]
{
new Permissions.Collections("TargetCollection*") { Read = true },
new Permissions.Data("TargetCollection*", "TargetTenant*") { Create = true },
};
await client.Roles.RemovePermissions(testRole, permissionsToRemove);
Check if a role exists
Check if the role testRole exists:
If a snippet doesn't work or you have feedback, please open a GitHub issue.
print(client.roles.exists(role_name="testRole")) # Returns True or False
console.log(await client.roles.exists("testRole")) // Returns true or false
exists, err := client.Roles().Exists().WithName("testRole").Do(ctx)
fmt.Println(exists) // Returns true or false
exists, err := client.Roles.Exists(ctx, "testRole")
if err != nil {
// handle error
panic(err)
}
fmt.Printf("testRole exists: %t\n", exists)
boolean exists = client.roles.exists(testRole);
System.out.println(exists); // Returns True or False
// In C#, we check by attempting to get the role
var retrievedRole = await client.Roles.Get(testRole);
bool exists = retrievedRole != null;
Console.WriteLine(exists);
Inspect a role
View the permissions assigned to a role.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
test_role = client.roles.get(role_name="testRole")
print(test_role)
print(test_role.collections_permissions)
print(test_role.data_permissions)
const testRole = await client.roles.byName("testRole")
console.log(testRole)
console.log(testRole?.collectionsPermissions)
console.log(testRole?.dataPermissions)
testRole, err := client.Roles().Getter().WithName("testRole").Do(ctx)
fmt.Println(testRole)
fmt.Println(testRole.Collections)
fmt.Println(testRole.Data)
role, err := client.Roles.Get(ctx, "testRole")
if err != nil {
// handle error
panic(err)
}
fmt.Printf("role: %s\n", role.ID)
fmt.Printf("collection permissions: %+v\n", role.Collections)
fmt.Printf("data permissions: %+v\n", role.Data)
Role testRoleData = client.roles.get(testRole).orElse(null);
System.out.println(testRoleData);
System.out.println(testRoleData.permissions()); // Combined list
var testRoleData = await client.Roles.Get(testRole);
Console.WriteLine(testRoleData);
List all roles
View all roles in the system and their permissions.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
all_roles = client.roles.list_all()
for role_name, role in all_roles.items():
print(role_name, role)
const allRoles = await client.roles.listAll()
for (const [key, value] of Object.entries(allRoles)) {
console.log(key)
}
allRoles, err := client.Roles().AllGetter().Do(ctx)
for _, role := range allRoles {
fmt.Println(role.Name, role)
}
roles, err := client.Roles.List(ctx)
if err != nil {
// handle error
panic(err)
}
for _, role := range roles {
fmt.Printf("%s\n", role.ID)
}
List<Role> allRoles = client.roles.list();
for (Role role : allRoles) {
System.out.println(role.name() + " " + role);
}
var allRoles = await client.Roles.ListAll();
foreach (var role in allRoles)
{
Console.WriteLine($"{role.Name} {role}");
}
List users with a role
List all users who have the role testRole.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
assigned_users = client.roles.get_user_assignments(role_name="testRole")
for user in assigned_users:
print(user)
const assignedUsers = await client.roles.userAssignments("testRole")
for (const users of assignedUsers) {
console.log(users)
}
assignedUsers, err := client.Roles().UserAssignmentGetter().
WithRole("testRole").
Do(ctx)
for _, user := range assignedUsers {
fmt.Println(user)
}
userIDs, err := client.Roles.AssignedUserIDs(ctx, "testRole")
if err != nil {
// handle error
panic(err)
}
for _, id := range userIDs {
fmt.Printf("assigned user: %s\n", id)
}
var assignedUsers = client.roles.assignedUserIds(testRole);
for (String user : assignedUsers) {
System.out.println(user);
}
var assignedUsers = await client.Roles.GetUserAssignments(testRole);
foreach (var assignment in assignedUsers)
{
Console.WriteLine(assignment.UserId);
}
Delete a role
Deleting a role will remove it from the system, and revoke the associated permissions from all users who had this role.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
client.roles.delete(role_name="testRole")
await client.roles.delete("testRole")
err = client.Roles().Deleter().WithName("testRole").Do(ctx)
err := client.Roles.Delete(ctx, "testRole")
if err != nil {
// handle error
panic(err)
}
client.roles.delete(testRole);
await client.Roles.Delete(testRole);
User management
Visit the Manage users page to learn more about assigning roles to users as well as creating, updating and deleting users.
Further resources
Questions and feedback
Have a question or feedback? Here's how to reach us.
