Connect to WCS

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

• Connect a browser to WCS through the WCS Console.

  • The WCS console is a multi-purpose tool. Login to manage your clusters, users, and billing.
  • The built-in Query console is useful to connect without a client application.

• Connect a client application to WCS through APIs.

  • For applications, use the WCS API and one of the client libraries to connect to WCS.

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

Connect with a browser

The WCS 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 WCS with a browser, follow these steps:

1. Open the WCS login page in a browser.
2. Click Login to Weaviate Cloud Services.
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 WCS console.
2. Click the silhouette of a person in the sidebar

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

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

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 WCS. Use API keys to connect client applications to WCS.

Disable MFA

To disable MFA, contact support.

Connect with an API

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

Retrieve your API keys

To retrieve your API keys, follow these steps:

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

3. Click the API keys button.
4. 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"

Python (v4)

Use an API key to connect to WCS.

import weaviate
from weaviate.auth import AuthApiKey

# Connect to a WCS instance
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
)

Python (v3)

import weaviate
import os

# Instantiate the client with the auth config
client = weaviate.Client(
    url="https://WEAVIATE_INSTANCE_URL",  # Replace with your Weaviate endpoint
    auth_client_secret=weaviate.auth.AuthApiKey(api_key=weaviate_key),  # Replace with your Weaviate instance API key
)

JavaScript/TypeScript

import weaviate, { ApiKey } from 'weaviate-ts-client';

// Instantiate the client with the auth config
const client = weaviate.client({
  scheme: 'https',
  host: 'WEAVIATE_INSTANCE_URL',  // Replace WEAVIATE_INSTANCE_URL with your instance URL
  apiKey: new ApiKey(weaviateKey),
});

Go

package main

import (
  "context"
  "fmt"
  "os"
  "github.com/weaviate/weaviate-go-client/v4/weaviate"
)

// Instantiate the client with the auth config
cfg := weaviate.Config{
  Host:"",  // Replace WEAVIATE_INSTANCE_URL with your instance URL
  Scheme: "http",
  AuthConfig: auth.ApiKey{Value: weaviateKey},
  Headers: nil,
}

client, err := weaviate.NewClient(cfg)
if err != nil{
  fmt.Println(err)
}

Java

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;

Config config = new Config("https", "WEAVIATE_INSTANCE_URL");
// Replace WEAVIATE_INSTANCE_URL with your instance URL
WeaviateClient client = WeaviateAuthClient.apiKey(config, weaviateKey);

Curl

# Replace WEAVIATE_INSTANCE_URL with your instance URL

curl https://WEAVIATE_INSTANCE_URL/v1/meta -H "Authorization: Bearer ${WEAVIATE_API_KEY}" | jq

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.

4. Choose the key scope, read-only or admin.
5. Click Generate to create the key.

Delete an API key

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

WCS 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.

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.

Troubleshooting

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

Reset your password

To reset your WCS password, follow these steps:

1. Go to the WCS login page.
2. Click on click the login button.
3. Click Forgot Password.
4. Check your email account for a password reset email from WCS.
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 WCS. 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.

Python (v4)

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 a WCS instance
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.

Python (v4)

import weaviate
from weaviate.auth import AuthApiKey

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

# Connect to a WCS instance
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. WCS 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 WCS 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 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:

• Python
• TypeScript/JavaScript
• Go
• Java

Support

For questions and support, try the following resources:

• Community forum
• GitHub
• Slack

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