Manage users

Added in 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.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

print(client.users.db.list_all())

console.log(await client.users.db.listAll())

users, err := client.Users().DB().Lister().Do(ctx)
fmt.Println(users)

users, err := client.Users.DB.List(ctx, rbac.ListUsersOptions{
  // Ask the server to report when each key was last used.
  IncludeLastUsedAt: true,
})
if err != nil {
  // handle error
  panic(err)
}
for _, u := range users {
  fmt.Printf("%s (active: %t)\n", u.ID, u.Active)
  // When the server has nothing to report it sends the zero time, not a
  // null value.
  if !u.CreatedAt.IsZero() {
    fmt.Printf("  created: %s\n", u.CreatedAt.Format(time.RFC3339))
  }
  if u.LastUsedAt.IsZero() {
    fmt.Println("  never used")
  } else {
    fmt.Printf("  last used: %s\n", u.LastUsedAt.Format(time.RFC3339))
  }
}

var allUsers = client.users.db.list();
System.out.println(allUsers);

var allUsers = await client.Users.Db.List();
Console.WriteLine(string.Join(", ", allUsers.Select(u => u.UserId)));

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.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

user_api_key = client.users.db.create(user_id="custom-user")
print(user_api_key)

let userApiKey 
userApiKey = await client.users.db.create("custom-user")
console.log(userApiKey)

userApiKey, err := client.Users().DB().Creator().WithUserID("custom-user").Do(ctx)
fmt.Println(userApiKey)

// Create returns the new user's API key. Store it securely; it cannot be
// retrieved again later.
apiKey, err := client.Users.DB.Create(ctx, "custom-user")
if err != nil {
  // handle error
  panic(err)
}
fmt.Printf("new API key: %s\n", apiKey)

String userApiKey = client.users.db.create(testUser);
System.out.println(userApiKey);

string userApiKey = await client.Users.Db.Create(testUser);
Console.WriteLine(userApiKey);

Example results

RXF1dU1VcWM1Q3hvVndYT0F1OTBOTDZLZWx0ME5kbWVJRVdPL25EVW12QT1fMXlDUEhUNjhSMlNtazdHcV92MjAw

Delete a database user

This example deletes a user called custom-user.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

await client.users.db.delete("custom-user")

deleted, err := client.Users().DB().Deleter().WithUserID("custom-user").Do(ctx)

err := client.Users.DB.Delete(ctx, "custom-user")
if err != nil {
  // handle error
  panic(err)
}

client.users.db.delete(testUser);

await client.Users.Db.Delete(testUser);

Rotate database user API key

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

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

new_api_key = client.users.db.rotate_key(user_id="custom-user")
print(new_api_key)

let newApiKey
newApiKey = await client.users.db.rotateKey("custom-user")
console.log(newApiKey)

newApiKey, err := client.Users().DB().KeyRotator().WithUserID("custom-user").Do(ctx)
fmt.Println(newApiKey)

newAPIKey, err := client.Users.DB.RotateKey(ctx, "custom-user")
if err != nil {
  // handle error
  panic(err)
}
fmt.Printf("rotated API key: %s\n", newAPIKey)

String newApiKey = client.users.db.rotateKey(testUser);
System.out.println(newApiKey);

string newApiKey = await client.Users.Db.RotateApiKey(testUser);
Console.WriteLine(newApiKey);

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.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

await client.users.db.assignRoles(["testRole", "viewer"], "custom-user")

err = client.Users().DB().RolesAssigner().
  WithUserID("custom-user").
  WithRoles("testRole", "viewer").
  Do(ctx)

err := client.Users.DB.AssignRoles(ctx, rbac.AssignRolesOptions{
  ID:    "custom-user",
  Roles: []string{"testRole", "viewer"},
})
if err != nil {
  // handle error
  panic(err)
}

client.users.db.assignRoles(testUser, testRole, "viewer");

await client.Users.Db.AssignRoles(testUser, new[] { testRole, "viewer" });

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.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

await client.users.db.revokeRoles("custom-user", "testRole")

err = client.Users().DB().RolesRevoker().
  WithUserID("custom-user").
  WithRoles("testRole").
  Do(ctx)

err := client.Users.DB.RevokeRoles(ctx, rbac.RevokeRolesOptions{
  ID:    "custom-user",
  Roles: []string{"testRole"},
})
if err != nil {
  // handle error
  panic(err)
}

client.users.db.revokeRoles(testUser, testRole);

await client.Users.Db.RevokeRoles(testUser, new[] { testRole });

Get a database user's roles

Retrieve the role information for any user.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

for role in user_roles:
    print(role)

let userRoles = await client.users.db.getAssignedRoles("custom-user")

for (const [role, value] of Object.entries(userRoles)) {
    console.log(role)
}

userRoles, err := client.Users().DB().RolesGetter().
  WithUserID("custom-user").
  WithIncludeFullRoles(true).
  Do(ctx)

for _, role := range userRoles {
  fmt.Println(role)
}

roles, err := client.Users.DB.AssignedRoles(ctx, rbac.AssignedRolesOptions{
  ID: "custom-user",
})
if err != nil {
  // handle error
  panic(err)
}
for _, role := range roles {
  fmt.Printf("%s\n", role.ID)
}

var userRoles = client.users.db.assignedRoles(testUser);
for (Role role : userRoles) {
  System.out.println(role.name());
}

var userRoles = await client.Users.Db.GetRoles(testUser);
foreach (var role in userRoles)
{
    Console.WriteLine(role.Name);
}

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.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

await client.users.oidc.assignRoles(["testRole", "viewer"], "custom-user",)

err = client.Users().OIDC().RolesAssigner().
  WithUserID("custom-user").
  WithRoles("testRole", "viewer").
  Do(ctx)

err := client.Users.OIDC.AssignRoles(ctx, rbac.AssignRolesOptions{
  ID:    "custom-user",
  Roles: []string{"testRole", "viewer"},
})
if err != nil {
  // handle error
  panic(err)
}

client.users.oidc.assignRoles(testUser, testRole, "viewer");

await client.Users.Oidc.AssignRoles(testUser, new[] { testRole, "viewer" });

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.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

await client.users.oidc.revokeRoles("testRole","custom-user")

err = client.Users().OIDC().RolesRevoker().
  WithUserID("custom-user").
  WithRoles("testRole").
  Do(ctx)

err := client.Users.OIDC.RevokeRoles(ctx, rbac.RevokeRolesOptions{
  ID:    "custom-user",
  Roles: []string{"testRole"},
})
if err != nil {
  // handle error
  panic(err)
}

client.users.oidc.revokeRoles(testUser, testRole);

await client.Users.Oidc.RevokeRoles(testUser, new[] { testRole });

Get an OIDC user's roles

Retrieve the role information for an OIDC user.

PythonJavaScript/TypeScriptGo (v5)Go (v6)JavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

for role in user_roles:
    print(role)

const userRoles = await client.users.oidc.getAssignedRoles("custom-user")

for (const [role, value] of Object.entries(userRoles)) {
    console.log(role)
}

userRoles, err := client.Users().OIDC().RolesGetter().
  WithUserID("custom-user").
  WithIncludeFullRoles(true).
  Do(ctx)

for _, role := range userRoles {
  fmt.Println(role)
}

roles, err := client.Users.OIDC.AssignedRoles(ctx, rbac.AssignedRolesOptions{
  ID: "custom-user",
})
if err != nil {
  // handle error
  panic(err)
}
for _, role := range roles {
  fmt.Printf("%s\n", role.ID)
}

var oidcUserRoles = client.users.oidc.assignedRoles(testUser);
for (Role role : oidcUserRoles) {
  System.out.println(role.name());
}

var oidcUserRoles = await client.Users.Oidc.GetRoles(testUser);
foreach (var role in oidcUserRoles)
{
    Console.WriteLine(role.Name);
}

Example results

testRole
viewer

Further resources

• RBAC: Overview
• RBAC: Configuration
• RBAC: Manage roles

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.