Skip to main content

Connect to WCD

There are two ways to connect to your Weaviate Cloud (WCD) instance:

Browser authentication uses a username and password for authentication. The Weaviate clients use API keys to authenticate.

Connect with a browser

The WCD dashboard lets you monitor and control your Weaviate clusters from your browser. It also provides account management tools and a GraphQL query app.

To connect to WCD with a browser, follow these steps:

  1. Open the WCD login page in a browser.
  2. Click Login to Weaviate Cloud.
  3. Enter your email address and password to authenticate.

Enable multi-factor authentication

Multi-factor authentication (MFA) increases the security of browser logins. To enable MFA, follow these steps.

  1. Use your browser to connect to the WCD console.
  2. Click the silhouette of a person in the sidebar

Enable MFA icon

  1. Click the 'Manage Two-Factor Authentication' button.
  2. Enter your username and password to authenticate to WCD.
  3. Open your authenticator application and scan the QR code.
  4. Enter the code from your application in WCD to complete the setup.

After you configure MFA, WCD prompts you to supply the one-time authentication code each time you log in.

Enter MFA code

MFA and applications

If you use a JavaScript or TypeScript client to connect an application to Weaviate, do not enable MFA for that client's account. There is no way to pass the the one-time authentication code, so the application cannot connect to WCD. Use API keys to connect client applications to WCD.

Disable MFA

To disable MFA, contact support.

Connect with an API

By default, API keys are enabled for all WCD clusters. Managed clusters have an administrator key and a read-only key. Sandbox clusters only have an administrator key.

API keys

Retrieve your API keys

To retrieve your API keys, follow these steps:

  1. Open the WCD console and find the panel for your cluster.
  2. Click the Details button.

API key button

  1. Click the API keys button.
  2. Copy the key and store it in a safe location.

Authenticate a client application

The Weaviate server authenticates every request.

If you use a tool like cURL, add your API key to the request header.

If you use a Weaviate client library, pass the API key when you instantiate the client connection. After the connection is established, you do not have to pass the API key when you make requests.

Do not hard-code your API key in your client code. Consider passing the API key as an environment variable or using a similar secure coding technique.

export WEAVIATE_API_KEY="replaceThisPartWithYourAPIKey"

Use an API key to connect to Weaviate Cloud.

import weaviate
from weaviate.auth import AuthApiKey

# Connect to Weaviate Cloud
client = weaviate.connect_to_wcs(
cluster_url=weaviate_url, # `weaviate_url`: your Weaviate URL
auth_credentials=AuthApiKey(weaviate_key), # `weaviate_key`: your Weaviate API key
)

Use an API key with a custom connection.

import weaviate
from weaviate.auth import AuthApiKey

# 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=AuthApiKey(weaviate_key), # `weaviate_key`: your Weaviate API key
)

Manage API keys

If you have a managed cluster, you can create and delete API keys.

There are two types of API key, ReadOnly and Admin.

  • Admin keys are read-write.
  • ReadOnly keys do not grant write access to the database.

Create an API key

If you have a managed cluster, you can create new API keys. New API keys are not available in Sandbox clusters.

WCS restarts the cluster when you add a new API key. If you have a stand-alone cluster, you will have a short downtime while the cluster restarts. There is no downtime if you have a high availability cluster.

To create a new API key, follow these steps:

  1. Click the Details button.
  2. Click the API keys button.
  3. Click Add Key.

Add API key UI

  1. Choose the key scope, read-only or admin.
  2. Click Generate to create the key.

Delete an API key

If you have a managed cluster, you can delete API keys.

WCD restarts the cluster when you delete an API key. If you have a stand-alone cluster, you will have a short downtime while the cluster restarts. There is no downtime if you have a high availability cluster.

To delete an API key, follow these steps:

  1. Click the Details button.
  2. Click the API keys button.
  3. Click the trash-can icon to delete the API key.

Add API key UI

Connect via the query app

The built in GraphQL query app connects to clusters in your organization without any additional authentication.

If you use the GraphQL query app to connect to a Weaviate instance that is not part of your organization, provide an API key for the remote instance.

To pass the API key, add it to the Headers at the bottom of the GraphQL query app.

API key in header

Troubleshooting

This section has solutions for some common problems. For additional help, contact support.

Reset your password

To reset your WCD password, follow these steps:

  1. Go to the WCD login page.
  2. Click on click the login button.
  3. Click Forgot Password.
  4. Check your email account for a password reset email from WCD.
  5. Click the link and follow the instructions to reset your password. The link is only valid for five minutes.

Connection timeouts

The new Python client uses the gRPC protocol to connect to WCD. The gRPC protocol improves query performance, but the protocol is sensitive to network speeds. If you run into timeout errors, increase the connection timeout value in your connection code.

from weaviate.classes.init import AdditionalConfig, Timeout
from weaviate.auth import AuthApiKey
import weaviate

# Set these environment variables
URL = os.getenv("WCS_URL")
APIKEY = os.getenv("WCS_API_KEY")

# Connect to Weaviate Cloud
client = weaviate.connect_to_wcs(
cluster_url=URL,
auth_credentials=AuthApiKey(APIKEY),
additional_config=AdditionalConfig(timeout=Timeout(init=10)),
)

# Check connection
client.is_ready()

Alternatively, leave the default timeout values, but skip the initial connection checks.

import weaviate
from weaviate.auth import AuthApiKey

# Set these environment variables
URL = os.getenv("WCS_URL")
APIKEY = os.getenv("WCS_API_KEY")

# Connect to Weaviate Cloud
client = weaviate.connect_to_wcs(
cluster_url=URL,
auth_credentials=AuthApiKey(APIKEY),
skip_init_checks=True,
)

# Check connection
client.is_ready()

gRPC health check error

Problem: gRPC returns a health check error after you update a managed cluster.

weaviate.exceptions.WeaviateGRPCUnavailableError: gRPC health check could not be completed.

Solution: Verify the cluster URL is correct and update the URL if needed.

When a managed cluster is updated, the cluster URL may change slightly. WCD still routes the old URL, so some connections work, however the new gRPC and the old HTTP URLS are different so connections that require gRCP fail.

To check the URLs, open the WCD Console and check the details panel for your cluster. If you prefix Cluster URL with grpc-, the Cluster URL and the Cluster gRPC URL should match.

Compare URLs

Compare the Cluster URL with the connection URL in your application. The old URL and the new URL are similar, but the new one may have an extra subdomain such as .c0.region.

If the URLs are different, update your application's connection code to use the new Cluster URL.

More resources

To authenticate with a Weaviate client library, see the following:

Support

For questions and support, try the following resources:

Weaviate also offers paid support services. If you have a contract with Weaviate, contact your sales representative for details.