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:

Python

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
)

JavaScript/TypeScript

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
});

Go

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)
}

Java

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

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

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
    ),
)

JavaScript/TypeScript

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
  })
});

Go

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)
}

Java

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.

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:

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:
  • Python
  • TypeScript/JavaScript
  • Go
  • Java
• 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.

Inference API status pages

• Cohere status
• Hugging Face status
• OpenAI status