Skip to main content

Manage users

Added in v1.29 and v1.30

Role-based access control (RBAC) is generally available in Weaviate from version v1.29.
User management is available from version v1.30.

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.

Weaviate differentiates multiple types of users. Database users are fully managed by the Weaviate instance, while OIDC users are managed by an external identity provider. Both types can be used together with RBAC.

On this page, you will find examples of how to programmatically manage users and their associated roles with Weaviate client libraries.

User types in Weaviate

Under the hood, Weaviate differentiates three types of users:

  • db_user: Database users that can be fully managed through the API.
  • db_env_user: Database users that are defined through the AUTHENTICATION_APIKEY_USERS environment variable and can only be updated through this variable and by restarting the Weaviate instance.
  • oidc: Users that can only be created/deleted through the external OIDC service.

User management ​

List all users​

This example shows how to get a list of all the users (db_user, db_env_user and oidc) in Weaviate.

print(client.users.db.list_all())
py docs  API docs
Example results
[
  UserDB(user_id='custom-user', role_names=['viewer', 'testRole'], user_type=<UserTypes.DB_DYNAMIC: 'db_user'>, active=True),
  UserDB(user_id='root-user', role_names=['root'], user_type=<UserTypes.DB_STATIC: 'db_env_user'>, active=True)
]

Create a database user​

This example creates a user called custom-user.

user_api_key = client.users.db.create(user_id="custom-user")
print(user_api_key)
py docs  API docs
Example results
RXF1dU1VcWM1Q3hvVndYT0F1OTBOTDZLZWx0ME5kbWVJRVdPL25EVW12QT1fMXlDUEhUNjhSMlNtazdHcV92MjAw

Delete a database user​

This example deletes a user called custom-user.

client.users.db.delete(user_id="custom-user")
py docs  API docs

Rotate database user API key​

This example updates (rotates) the API key for custom-user.

new_api_key = client.users.db.rotate_key(user_id="custom-user")
print(new_api_key)
py docs  API docs
Example results
SSs3WGVFbUxMVFhlOEsxVVMrQVBzM1VhQTJIM2xXWngwY01HaXFYVnM1az1fMXlDUEhUNjhSMlNtazdHcV92MjAw

Database users: Permissions management ​

Assign a role to a database user​

A custom user can have any number of roles assigned to them (including none). The role can be a predefined role (e.g. viewer) or a custom role.

This example assigns the custom testRole role and predefined viewer role to custom-user.

client.users.db.assign_roles(user_id="custom-user", role_names=["testRole", "viewer"])
py docs  API docs

Remove a role from a database user​

You can revoke one or more roles from a specific user.

This example removes the role testRole from the user custom-user.

client.users.db.revoke_roles(user_id="custom-user", role_names="testRole")
py docs  API docs

Get a database user's roles​

Retrieve the role information for any user.

user_roles = client.users.db.get_assigned_roles("custom-user")

for role in user_roles:
    print(role)
py docs  API docs
Example results
testRole
viewer

OIDC users: Permissions management ​

When using OIDC, an identity provider authenticates the user and issues tokens, which are then validated by Weaviate. These users can be assigned roles with custom permissions using RBAC.

Assign a role to an OIDC user​

An OIDC user can have any number of roles assigned to them (including none). The role can be a predefined role (e.g. viewer) or a custom role.

This example assigns the custom testRole role and predefined viewer role to custom-user.

client.users.oidc.assign_roles(user_id="custom-user", role_names=["testRole", "viewer"])
py docs  API docs

Remove a role from an OIDC user​

You can revoke one or more roles from a specific OIDC user.

This example removes the role testRole from the user custom-user.

client.users.oidc.revoke_roles(user_id="custom-user", role_names="testRole")
py docs  API docs

Get an OIDC user's roles​

Retrieve the role information for an OIDC user.

user_roles = client.users.oidc.get_assigned_roles("custom-user")

for role in user_roles:
    print(role)
py docs  API docs
Example results
testRole
viewer

Further resources​

Questions and feedback​

If you have any questions or feedback, let us know in the user forum.