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.
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.
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:
- Python
- JavaScript/TypeScript
- Go
- Java
- Curl
import weaviate
# Instantiate the client with the auth config
client = weaviate.Client(
url="https://some-endpoint.weaviate.network", # Replace w/ your endpoint
auth_client_secret=weaviate.AuthApiKey(api_key="YOUR-WEAVIATE-API-KEY"), # Replace w/ your Weaviate instance API key
)
import weaviate, { ApiKey } from 'weaviate-ts-client';
// Instantiate the client with the auth config
const client = weaviate.client({
scheme: 'https',
host: 'some-endpoint.weaviate.network',
apiKey: new ApiKey('YOUR-WEAVIATE-API-KEY'), // Replace w/ your Weaviate instance API key
});
package main
import (
"context"
"fmt"
"github.com/weaviate/weaviate-go-client/v4/weaviate"
)
// Instantiate the client with the auth config
cfg := weaviate.Config{
Host:"some-endpoint.weaviate.network",
Scheme: "http",
AuthConfig: auth.ApiKey{Value: "YOUR-WEAVIATE-API-KEY"}, // Replace w/ your Weaviate instance API key
Headers: nil,
}
client, err := weaviate.NewClient(cfg)
if err != nil{
fmt.Println(err)
}
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;
Config config = new Config("https", "some-endpoint.weaviate.network");
WeaviateClient client = WeaviateAuthClient.apiKey(config, "YOUR-WEAVIATE-API-KEY"); // Replace w/ your Weaviate instance API key
curl https://some-endpoint.weaviate.network/v1/meta -H "Authorization: Bearer YOUR-WEAVIATE-API-KEY" | jq
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:
- Python
- JavaScript/TypeScript
- Go
- Java
import weaviate
# Instantiate the client with the auth config
client = weaviate.Client(
url="https://some-endpoint.weaviate.network", # Replace w/ your endpoint
auth_client_secret=weaviate.AuthClientPassword(
username = "WCS_USERNAME", # Replace w/ your WCS username
password = "WCS_PASSWORD", # Replace w/ your WCS password
),
)
import weaviate, { AuthUserPasswordCredentials } from 'weaviate-ts-client';
const client = weaviate.client({
scheme: "https",
host: "some-endpoint.weaviate.network", // Replace w/ your endpoint
authClientSecret: new AuthUserPasswordCredentials({
username: "WCS_USERNAME", // Replace w/ your WCS username
password: "WCS_PASSWORD", // Replace w/ your WCS password
})
});
package main
import (
"context"
"fmt"
"github.com/weaviate/weaviate-go-client/v4/weaviate"
)
cfg := weaviate.Config{
Host:"some-endpoint.weaviat}e.network", // Replace w/ your endpoint
Scheme: "https",
AuthConfig: auth.ResourceOwnerPasswordFlow{
Username: "WCS_USERNAME", // Replace w/ your WCS username
Password: "WCS_PASSWORD", // Replace w/ your WCS password
}
}
client, err := weaviate.NewClient(cfg)
if err != nil {
fmt.Println(err)
}
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;
Config config = new Config("https", "some-endpoint.weaviate.network"); // Replace w/ your endpoint
WeaviateAuthClient.clientPassword(
config,
"WCS_USERNAME", // Replace w/ your WCS username
"WCS_PASSWORD", // Replace w/ your WCS password
);
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.
This is the "Resource Owner Password Flow" method.
Weaviate console
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:
{ "Authorization": "Bearer YOUR_API_KEY" }
Pass the credentials as an additional header via the Header
tab located towards the bottom of the console:

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:
- To revoke your API key, navigate to the Details button as described here.
- To reset your WCS password, you can do so from WCS (click "Sign In" and then "Forgot Password").
Read more
If you are interested, you can read more about authentication below:
- Authentication with Weaviate clients:
- About OIDC.
- About KeyCloak, the OIDC token issuer server used with WCS.
More resources
Support & Troubleshooting
All Weaviate users are welcome to join our community Slack and forum.
Additionally, paid customers can also contact support via channels provided during cluster creation and/or on-boarding.
For general contact details please see this page.