Role-based access control (RBAC) is a method of restricting access to resources based on the roles of users. In Weaviate, RBAC allows you to **[define roles and assign permissions](weaviate-configuration-rbac-manage-roles.md)** to those roles. Users can then be assigned to roles and inherit the permissions associated with those roles.

Weaviate comes with a set of predefined roles. These roles are:

- `root`: The root role has full access to all resources in Weaviate.
- `viewer`: The viewer role has read-only access to all resources in Weaviate.

The `root` role can be assigned through the Weaviate configuration file. A predefined role cannot be modified. The user can, however, be assigned additional roles through the Weaviate API.

:::callout{intent="tip" title="Root user requirement in older versions"}
In Weaviate versions `v1.30.6` and `v1.31.0` or below, if RBAC is enabled, you must configure at least one user with the built-in root role. Otherwise, Weaviate will not start. This requirement was removed in versions `v1.30.7` and `v1.31.1`.
:::

## Docker

RBAC authorization can be configured using environment variables. In Docker Compose, set them in the configuration file (`docker-compose.yml`) such as in the following example:

```yaml
services:
  weaviate:
    ...
    environment:
      ...
      # Example authentication configuration using API keys
      # OIDC access can also be used with RBAC
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'false'
      AUTHENTICATION_APIKEY_ENABLED: 'true'
      AUTHENTICATION_APIKEY_ALLOWED_KEYS: 'root-user-key'
      AUTHENTICATION_APIKEY_USERS: 'root-user'

      # Authorization configuration
      # Enable RBAC
      AUTHORIZATION_RBAC_ENABLED: 'true'

      # Provide pre-configured roles to users
      # This assumes that the relevant user has been authenticated and identified

      # You MUST define at least one root user
      AUTHORIZATION_RBAC_ROOT_USERS: 'root-user'
      # Enable the runtime user management
      AUTHENTICATION_DB_USERS_ENABLED: 'true'
```

This configuration:

- Enables RBAC
- Configures `root-user` as a user with built-in admin permissions

You can connect to your instance with the root user in order to [create new users](weaviate-configuration-rbac-manage-users.md) which can be assigned custom roles and permissions using the [REST API](/weaviate/api/rest#tag/authz) or [programmatically using a client library](weaviate-configuration-rbac-manage-roles.md).

:::callout{intent="tip" title="TIP: User management API available from `v1.30`"}
Instead of adding additional users via the `AUTHENTICATION_APIKEY_USERS` environment variable, we suggest using the [user management API](weaviate-configuration-rbac-manage-users.md) which you can use to create and delete users, manage their roles and rotate their API keys.
:::

## Kubernetes

For Kubernetes deployments using Helm, API key authentication can be configured in the `values.yaml` file under the `authorization` section. Here's an example configuration:

```yaml
# Example authentication configuration using API keys
authentication:
  anonymous_access:
    enabled: false
  apikey:
    enabled: true
    allowed_keys:
      - root-user-key
    users:
      - root-user

# Authorization configuration
authorization:
  rbac:
    # Enable RBAC
    enabled: true
    # Provide pre-configured roles to users
    # This assumes that the relevant user has been authenticated and identified
    #
    # You MUST define at least one root user
    root_users:
    - root-user
```

This configuration:

- Enables RBAC
- Configures `root-user` as a user with built-in admin permissions

You can connect to your instance with the root user in order to [create new users](weaviate-configuration-rbac-manage-users.md) which can be assigned custom roles and permissions using the [REST API](/weaviate/api/rest#tag/authz) or [programmatically using a client library](weaviate-configuration-rbac-manage-roles.md).

## Authorization audit logging

When RBAC is enabled, Weaviate automatically logs all authorization decisions for audit purposes. These logs capture:

- User making the request
- Action being authorized
- Authorization decision (allowed or denied)
- User groups (if applicable)
- Source IP address (optional)
- Resource being accessed

Audit logs are written at the `info` level for successful authorizations and `error` level for denials. No additional configuration is required - audit logging is automatic when RBAC is enabled.

For details on log format, how to collect and analyze authorization audit logs, and best practices for log retention, see the [Logging configuration page](../monitoring-and-logging/logging.md#authorization-audit-logging).

## RBAC and performance

RBAC is a powerful feature that allows you to define fine-grained access control policies. However, it can also have an impact on performance as each operation must be checked against the user's permissions.

The exact performance impact will depend on your setup and use case. In our internal testing, the most significant performance impact was seen for object creation operations.

We did not observe additional performance penalties for using custom roles over the built-in roles.

Here are some tips to optimize performance when using RBAC:

- Monitor object creation performance
- Use a high availability (i.e. 3+ nodes) setup to distribute the load

## Further resources

- [RBAC: Overview](weaviate-configuration-rbac.md)
- [RBAC: Manage roles](weaviate-configuration-rbac-manage-roles.md)
- [RBAC: Manage users](weaviate-configuration-rbac-manage-users.md)
- [RBAC: Tutorial](../guides-tutorials/rbac.md)

## Questions and feedback

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

::::card-grid
:::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"}
Ask questions and connect with other developers on our **Community forum**.
:::

:::card{title="Support" href="/guides/support-overview" icon="life-buoy"}
Weaviate Cloud user or customer? Find the right channel on the **Support page**.
:::
::::

## Related pages

- [Agents](./agents-index.md)
- [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md)
- [APIs](./apis-index.md)
- [Authorization and authentication](./authorization-and-authentication-index.md)
- [Benchmarks](./benchmarks-index.md)
- [Best practices](./best-practices-index.md)
- [Client libraries](./clients-index.md)
- [Client Libraries / SDKs](./client-libraries-index.md)
- [Cloud](./cloud-index.md)
- [Cloud account management](./cloud-account-management-index.md)

# Agent Instructions

This portal answers questions programmatically. To receive a synthesized,
source-cited answer instead of crawling page by page, append the `?ask=`
query parameter to any page URL on this site:

    /guides/quickstart?ask=how+do+I+authenticate

Optional parameters:

- `&goal=<what-you-are-trying-to-do>` steers the answer toward your
  objective (e.g. `&goal=write+a+python+client`).
- `&version=<label>` scopes the answer to a mounted version when the
  portal publishes more than one.

The response is `text/markdown`: the answer followed by a `# Sources` list
of the portal pages it was grounded in. Status codes are the contract:

- `200` — the answer; `402` — the portal owner’s plan or answer credits are
  exhausted (surface this to your operator; do NOT retry); `429` — you are
  rate-limited; back off for the `Retry-After` seconds; `503` — the answer
  lane is temporarily unavailable; fall back to crawling the `.md` pages.

For the full corpus map read `llms.txt` at the site root; for the tool
surface (search + page fetch as MCP tools) see `/mcp`.