A Clean Onboarding Checklist for New Users Who Need the Vector Database API Key, Console Access, and Project Entry Points

Starting with a vector database for the first time involves a handful of discrete steps that each need to happen in the right order. The steps themselves are not difficult, but when documentation is scattered across multiple pages, or when a platform has changed how things work recently, small gaps in the process can stall progress for longer than they should.

This checklist covers everything a new user needs to go from zero to a working connection: creating an account and cluster, finding and storing credentials correctly, installing the client library, and verifying the connection works. It also covers the places where onboarding most commonly gets stuck.

What Onboarding a Vector Database Actually Involves

At a high level, onboarding a vector database has four components regardless of which platform you are using.

Provisioning is creating the actual database instance — whether that is a managed cluster in a cloud console, a local Docker container, or a Kubernetes deployment. Most managed platforms have a console that handles this through a UI.

Authentication is getting the credentials that let your code connect to that instance. This is usually an API key, sometimes paired with an endpoint URL. The specifics vary: some platforms generate a default key on cluster creation, others require you to create one explicitly.

Client setup is installing and configuring the language-specific library you will use to talk to the database. Most platforms provide official clients for Python, JavaScript, Go, and Java, each with their own installation and connection patterns.

Verification is confirming that all of the above actually works before you start building. A simple connectivity check at the end of setup saves debugging time later.

Each of these steps has at least one common failure mode, most of which are well-known and avoidable if you know what to look for.

Common Onboarding Failure Points

Missing API key on new clusters. Some platforms enable role-based access control by default on newly created clusters and do not generate a key automatically. The cluster is running and accessible, but any attempt to connect is rejected because there is nothing to authenticate with yet. The fix is to create a key manually through the console before trying to connect with code.

Hard-coded credentials. Developers under time pressure paste API keys directly into scripts to get something working quickly. This works until the key is rotated, the script ends up in version control, or someone shares the file. Storing credentials as environment variables from the start avoids this entirely.

Wrong credential format. Client libraries are specific about how credentials should be provided. A key passed as a plain string often fails even when the key value is correct, because the library expects a structured credential object. The error message typically says something about anonymous access or authentication failure, which makes it look like a key problem when it is actually a formatting problem.

gRPC timeouts on slow networks. Modern vector database clients often use gRPC for the initial connection handshake. gRPC is more sensitive to network latency than REST, and the default timeout is sometimes not enough on slow or restricted connections. Increasing the timeout or skipping the init checks resolves this.

External model API keys. If your project uses a hosted embedding or generation model from a third-party provider, that provider’s API key needs to be passed separately alongside your vector database credentials. Forgetting this step means the cluster connects fine but any operation that calls the external model fails.

Weaviate Onboarding Checklist

Step 1 — Create a Cluster

Go to console.weaviate.cloud and sign up or log in. Navigate to the Clusters tab and create a free Sandbox cluster. Provisioning takes one to three minutes — a checkmark appears in the console when the cluster is ready.

Sandbox clusters are free and last 14 days. They are suitable for learning and prototyping. Note that Weaviate appends a random suffix to sandbox cluster names to ensure uniqueness across accounts.

Step 2 — Retrieve Your Credentials

Open the Cluster details panel for your cluster. You need two values:

• REST Endpoint URL — the address your client will connect to
• API Key — the credential used to authenticate

Important for v1.30+ clusters: Clusters running Weaviate v1.30 or later have RBAC enabled by default and do not come with a pre-created API key. You need to create one before you can connect:

1. Go to Cluster details → API Keys → New key
2. Give it a descriptive name and assign the admin role
3. Copy the key immediately — it will not be shown again

Step 3 — Store Credentials as Environment Variables

Never put credentials directly in code. Set them as environment variables:

export WEAVIATE_URL="replaceThisWithYourRESTEndpointURL"
export WEAVIATE_API_KEY="replaceThisWithYourAPIKey"

For production environments, use your infrastructure’s secret management system (GitHub Actions secrets, AWS Secrets Manager, HashiCorp Vault, etc.) rather than shell exports.

Step 4 — Install the Client Library

For Python:

pip install weaviate-client

If your project uses Weaviate’s Agents feature:

pip install "weaviate-client[agents]"

Step 5 — Connect and Verify

Run this to confirm the connection works:

import weaviate
from weaviate.classes.init import Auth
import os

weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,
    auth_credentials=Auth.api_key(weaviate_api_key),
)

print(client.is_ready())  # True means connected and ready

client.close()

True means everything is working. If you get False or an exception, check that the environment variables are set, that the key was created in the console, and that Auth.api_key() is wrapping the key rather than passing it as a bare string.

Step 6 — Handle Connection Timeouts

If the connection hangs or raises a gRPC timeout error, increase the timeout values:

from weaviate.classes.init import AdditionalConfig, Timeout, Auth

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,
    auth_credentials=Auth.api_key(weaviate_api_key),
    additional_config=AdditionalConfig(
        timeout=Timeout(init=30, query=60, insert=120)
    )
)

The values are in seconds. init controls the connection handshake timeout, query controls how long a search can take, and insert controls how long an ingestion operation can run.

Step 7 — Add Third-Party API Keys

If your project uses an external embedding or generation model — Cohere, OpenAI, or another provider — pass that provider’s API key via headers at connection time:

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,
    auth_credentials=Auth.api_key(weaviate_api_key),
    headers={
        "X-Cohere-Api-Key": os.environ["COHERE_API_KEY"]
    }
)

Each provider has a specific header name. The Weaviate documentation lists the correct header for each supported integration.

Quick Reference