Skip to main content

Authentication

Overview

To ensure security in a production environment, Weaviate instances on Weaviate Cloud Services (WCS) come pre-configured with authentication enabled (except for sandbox instances, where it is optional).

Authentication options

You have two options for authenticating into a WCS instance.

  • Using an API key (recommended method), or
  • Using the account owner's WCS username and password.
Recommendation: Use the API key + a Weaviate client

Generally, we recommend authenticating with the API key, using a Weaviate client (e.g. Python client).

API key permissions

All Weaviate instances with authentication will generate API keys with full admin (read and write) access.

Each paid WCS instance will also come with a read-only API key in addition to the full admin API key.

Manage API keys

You can create and delete individual API keys for your (non-sandbox) instances, as well as get their details.

To do so, first click Details button for your cluster, followed by the API keys button.

This will show a list of your available keys as a table, as well as their permissions (scope).

  • To create a key, click the Add key button and follow the instructions.
  • To delete a key, click on the trash can icon next to the relevant key.
  • To copy a key, click on the copy can icon next to the relevant key.
Keep your API key secret

Please ensure that your API key is kept secret for security. The above image is for demonstration purposes only.

Steps for authentication

An API key

To authenticate against Weaviate with an API key, each request needs to include the key in its header. The easiest way to do this is with a Weaviate client at instantiation, as shown in the code examples below:

Use an API key to connect to WCS.

import weaviate
import os

# Connect to a WCS instance
client = weaviate.connect_to_wcs(
cluster_url=os.getenv("YOUR_WCS_URL"), # Set this environment variable
auth_credentials=weaviate.auth.AuthApiKey(
os.getenv("YOUR_WCS_AUTH_KEY")
), # Set this environment variable
)

Use an API key with a custom connection.

import weaviate
import os

# Connect to a local Weaviate instance
client = weaviate.connect_to_custom(
http_host="localhost",
http_port=8080,
http_secure=False,
grpc_host="localhost",
grpc_port=50051,
grpc_secure=False,
auth_credentials=weaviate.auth.AuthApiKey(
os.getenv("YOUR_API_KEY")
), # Set this environment variable
)

This way, every request made using the client will include the API key.

Manually adding the key to the header.

If using a Weaviate client is not possible, you can manually include the API key in the request header as below:

Authorization: Bearer YOUR-WEAVIATE-API-KEY

Replacing YOUR-WEAVIATE-API-KEY with your API key.

WCS username and password

To authenticate against Weaviate with your WCS username and password, each request needs to include the an OpenID Connect (OIDC) token in its header. As with the API key-based authentication, the easiest way to do this is with a Weaviate client at instantiation, by providing your WCS username and password as shown below:

import weaviate
import os

client = weaviate.connect_to_wcs(
cluster_url="https://your-wcs-endpoint.weaviate.network",
auth_credentials=weaviate.AuthClientPassword(
username=os.getenv("YOUR_WCS_USER_NAME"), # Set this environment variable
password=os.getenv("YOUR_WCS_PASSWORD"), # Set this environment variable
),
)

This way, every request made using the client will include an OIDC token.

Manually adding the key to the header.

If using a Weaviate client is not possible, you can manually include an OIDC token in the request header as below.

Authorization: Bearer TOKEN

Replacing TOKEN with your OIDC token.

Please note that OIDC tokens will periodically expire, so new tokens must be obtained and used. This can be done using the "refresh token", however this is outside the scope of the documentation.

To automate this workflow, we strongly recommend that you use your preferred Weaviate client library for username and password-based authentication.

What OIDC "flow" is this?

This is the "Resource Owner Password Flow" method.

Weaviate console

Automatic authentication for your WCS instances

If you are using the GraphQL console to query WCS instances under the same account, the console will automatically include the relevant credentials for you. In other words, your queries will be automatically authenticated.

If you are querying an external Weaviate instance through the WCS console, you can pass authentication credentials (e.g. your API key) in this format:

Headers tab
{ "Authorization": "Bearer YOUR_API_KEY" }

Pass the credentials as an additional header via the Header tab located towards the bottom of the console:

WCS Headers Authorization Bearer example

This will authenticate your requests against the Weaviate instance.

Resetting credentials

If you would like to reset your credentials, you can do so as follows:

More resources

If you are interested, you can read more about authentication below: