---
title: "Custom connections"
description: "Custom connection configurations with code examples in Python and TypeScript."
url: https://docs.weaviate.io/weaviate/connections/connect-custom
---

# Custom connections

The [Python client](https://docs.weaviate.io/weaviate/client-libraries/python) and the [TypeScript client](https://docs.weaviate.io/weaviate/client-libraries/typescript) provide helper methods for common connection types. They also provide custom methods for when you need additional connection configuration.

If you are using one of the other clients, the standard connection methods are configurable for all connections.

**Python**

```py
import weaviate, os
from weaviate.classes.init import Auth
from weaviate.config import AdditionalConfig, Timeout

# Best practice: store your credentials in environment variables
http_host = os.environ["WEAVIATE_HTTP_HOST"]
grpc_host = os.environ["WEAVIATE_GRPC_HOST"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_custom(
    http_host=http_host,        # Hostname for the HTTP API connection
    http_port=443,              # Default is 80, WCD uses 443
    http_secure=True,           # Whether to use https (secure) for the HTTP API connection
    grpc_host=grpc_host,        # Hostname for the gRPC API connection
    grpc_port=443,              # Default is 50051, WCD uses 443
    grpc_secure=True,           # Whether to use a secure channel for the gRPC API connection
    auth_credentials=Auth.api_key(weaviate_api_key),    # API key for authentication
)

print(client.is_ready())
```

**JavaScript/TypeScript**

```ts
import weaviate, { WeaviateClient } from '@weaviate/node';

// Set these environment variables
// WEAVIATE_HTTP_HOST       your Weaviate instance URL
// WEAVIATE_GRPC_HOST   your Weaviate instance GPC URL
// WEAVIATE_API_KEY   your Weaviate instance API key

const client = await weaviate.connectToCustom(
 {
    httpHost: process.env.WEAVIATE_HTTP_HOST,  // URL only, no http prefix
    httpPort: 443,
    grpcHost: process.env.WEAVIATE_GRPC_HOST,
    grpcPort: 443,        // Default is 50051, WCD uses 443
    grpcSecure: true,
    httpSecure: true,
    authCredentials: new weaviate.ApiKey(process.env.WEAVIATE_API_KEY),
  })

console.log(client)
```

**Java**

```java
// Best practice: store your credentials in environment variables
String httpHost = System.getenv("WEAVIATE_HTTP_HOST");
String grpcHost = System.getenv("WEAVIATE_GRPC_HOST");
String weaviateApiKey = System.getenv("WEAVIATE_API_KEY");
String cohereApiKey = System.getenv("COHERE_API_KEY");

WeaviateClient client =
    WeaviateClient.connectToCustom(config -> config.scheme("https") // Corresponds to http_secure=True and grpc_secure=True
        .httpHost(httpHost)
        .httpPort(443)
        .grpcHost(grpcHost)
        .grpcPort(443)
        .authentication(Authentication.apiKey(weaviateApiKey))
        .setHeaders(Map.of("X-Cohere-Api-Key", cohereApiKey)));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources
```

**C#**

```csharp
// Best practice: store your credentials in environment variables
string httpHost = Environment.GetEnvironmentVariable("WEAVIATE_HTTP_HOST");
string grpcHost = Environment.GetEnvironmentVariable("WEAVIATE_GRPC_HOST");
string weaviateApiKey = Environment.GetEnvironmentVariable("WEAVIATE_API_KEY");
string cohereApiKey = Environment.GetEnvironmentVariable("COHERE_API_KEY");

WeaviateClient client = await WeaviateClientBuilder
    .Custom(
        restEndpoint: httpHost,
        restPort: "443",
        grpcEndpoint: grpcHost,
        grpcPort: "443",
        useSsl: true
    )
    .WithCredentials(Auth.ApiKey(weaviateApiKey))
    .WithHeaders(new Dictionary<string, string> { { "X-Cohere-Api-Key", cohereApiKey } })
    .BuildAsync();

var isReady = await client.IsReady();
Console.WriteLine(isReady);
```

## Environment variables

> [!WARNING]
>
> Do not hard-code API keys or other credentials in your client code. Use environment variables or a similar secure coding technique instead.

Environment variables keep sensitive details out of your source code. Your application imports the information to runtime.

**Set an environment variable.**

In these examples, the environment variable names are in UPPER\_CASE.

**Bash**

```bash
export WEAVIATE_URL="http://localhost:8080"
export WEAVIATE_API_KEY="sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz"
```

**Windows PowerShell**

```shell
$Env:WEAVIATE_URL="http://localhost:8080"
$Env:WEAVIATE_API_KEY="sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz"
```

**Windows Command Prompt**

```shell
set WEAVIATE_URL=http://localhost:8080
set WEAVIATE_API_KEY=sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz
```

**Import an environment variable.**

**Python**

```python
weaviate_url = os.getenv("WEAVIATE_URL")
weaviate_key = os.getenv("WEAVIATE_API_KEY")
```

**JavaScript/TypeScript**

```js
const weaviateUrl = process.env.WEAVIATE_URL;
const weaviateKey = process.env.WEAVIATE_API_KEY;
```

**Go (v5)**

```go
weaviateUrl := os.Getenv("WEAVIATE_URL")
weaviateKey := os.Getenv("WEAVIATE_API_KEY")
```

## gRPC Timeouts

The Python client v4 and TypeScript client v3 use [gRPC](https://docs.weaviate.io/weaviate/api/grpc). The gRPC protocol is sensitive to network delay. If you encounter connection timeouts, adjust the timeout values for initialization, queries, and insertions.

**Python**

```py
import weaviate, os
from weaviate.classes.init import Auth
from weaviate.config import AdditionalConfig, Timeout

# Best practice: store your credentials in environment variables
http_host = os.environ["WEAVIATE_HTTP_HOST"]
grpc_host = os.environ["WEAVIATE_GRPC_HOST"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_custom(
    http_host=http_host,        # Hostname for the HTTP API connection
    http_port=443,              # Default is 80, WCD uses 443
    http_secure=True,           # Whether to use https (secure) for the HTTP API connection
    grpc_host=grpc_host,        # Hostname for the gRPC API connection
    grpc_port=443,              # Default is 50051, WCD uses 443
    grpc_secure=True,           # Whether to use a secure channel for the gRPC API connection
    auth_credentials=Auth.api_key(weaviate_api_key),    # API key for authentication
    additional_config=AdditionalConfig(
        timeout=Timeout(init=30, query=60, insert=120)  # Values in seconds
    )
)

print(client.is_ready())
```

**JavaScript/TypeScript**

```ts
import weaviate, { WeaviateClient } from '@weaviate/node';

// Set these environment variables
// WEAVIATE_HTTP_HOST       your Weaviate instance URL
// WEAVIATE_GRPC_HOST   your Weaviate instance GPC URL
// WEAVIATE_API_KEY   your Weaviate instance API key

const client: WeaviateClient = await weaviate.connectToCustom(
  {
   httpHost: process.env.WEAVIATE_HTTP_HOST,  // URL only, no http prefix
   httpPort: 443,
   grpcHost: process.env.WEAVIATE_GRPC_HOST,
   grpcPort: 443,        // Default is 50051, WCD uses 443
   grpcSecure: true,
   httpSecure: true,
   authCredentials: new weaviate.ApiKey(process.env.WEAVIATE_API_KEY),
   timeout: { init: 30, query: 60, insert: 120 } // Values in seconds
  }
)

console.log(client)
```

**Java**

```java
// Best practice: store your credentials in environment variables
String httpHost = System.getenv("WEAVIATE_HTTP_HOST");
String grpcHost = System.getenv("WEAVIATE_GRPC_HOST");
String weaviateApiKey = System.getenv("WEAVIATE_API_KEY");
String cohereApiKey = System.getenv("COHERE_API_KEY");

WeaviateClient client =
    WeaviateClient.connectToCustom(config -> config.scheme("https") // Corresponds to http_secure=True and grpc_secure=True
        .httpHost(httpHost)
        .httpPort(443)
        .grpcHost(grpcHost)
        .grpcPort(443)
        .authentication(Authentication.apiKey(weaviateApiKey))
        .setHeaders(Map.of("X-Cohere-Api-Key", cohereApiKey))
        .timeout(30, 60, 120)); // Values in seconds

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources
```

**C#**

```csharp
// Best practice: store your credentials in environment variables
string httpHost = Environment.GetEnvironmentVariable("WEAVIATE_HTTP_HOST");
string grpcHost = Environment.GetEnvironmentVariable("WEAVIATE_GRPC_HOST");
string weaviateApiKey = Environment.GetEnvironmentVariable("WEAVIATE_API_KEY");
string cohereApiKey = Environment.GetEnvironmentVariable("COHERE_API_KEY");

WeaviateClient client = await WeaviateClientBuilder
    .Custom(
        restEndpoint: httpHost,
        restPort: "443",
        grpcEndpoint: grpcHost,
        grpcPort: "443",
        useSsl: true
    )
    .WithCredentials(Auth.ApiKey(weaviateApiKey))
    .WithHeaders(new Dictionary<string, string> { { "X-Cohere-Api-Key", cohereApiKey } })
    .WithInitTimeout(TimeSpan.FromSeconds(30))
    .WithQueryTimeout(TimeSpan.FromSeconds(60))
    .WithInsertTimeout(TimeSpan.FromSeconds(120))
    .BuildAsync();

var isReady = await client.IsReady();
Console.WriteLine(isReady);
```

## Third party API keys

Integrations that use external APIs often need API keys. To add third party API keys, follow these examples:

**Python**

```py
import weaviate, os
from weaviate.classes.init import Auth
from weaviate.config import AdditionalConfig, Timeout

# Best practice: store your credentials in environment variables
http_host = os.environ["WEAVIATE_HTTP_HOST"]
grpc_host = os.environ["WEAVIATE_GRPC_HOST"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]
cohere_api_key = os.environ["COHERE_API_KEY"]

client = weaviate.connect_to_custom(
    http_host=http_host,        # Hostname for the HTTP API connection
    http_port=443,              # Default is 80, WCD uses 443
    http_secure=True,           # Whether to use https (secure) for the HTTP API connection
    grpc_host=grpc_host,        # Hostname for the gRPC API connection
    grpc_port=443,              # Default is 50051, WCD uses 443
    grpc_secure=True,           # Whether to use a secure channel for the gRPC API connection
    auth_credentials=Auth.api_key(weaviate_api_key),    # API key for authentication
    headers={"X-Cohere-Api-Key": cohere_api_key},       # Third party API key (e.g. Cohere)
)

print(client.is_ready())
```

**JavaScript/TypeScript**

```ts
import weaviate, { WeaviateClient } from '@weaviate/node';

// Set these environment variables
// WEAVIATE_HTTP_HOST       your Weaviate instance URL
// WEAVIATE_GRPC_HOST   your Weaviate instance GPC URL
// WEAVIATE_API_KEY   your Weaviate instance API key

const client = await weaviate.connectToCustom(
 {
    httpHost: process.env.WEAVIATE_HTTP_HOST,  // URL only, no http prefix
    httpPort: 443,
    grpcHost: process.env.WEAVIATE_GRPC_HOST,
    grpcPort: 443,        // Default is 50051, WCD uses 443
    grpcSecure: true,
    httpSecure: true,
    authCredentials: new weaviate.ApiKey(process.env.WEAVIATE_API_KEY),
    headers: {
      'X-Cohere-Api-Key': process.env.COHERE_API_KEY || ''
    }
  })

console.log(client)
```

**Java**

```java
// Best practice: store your credentials in environment variables
String httpHost = System.getenv("WEAVIATE_HTTP_HOST");
String grpcHost = System.getenv("WEAVIATE_GRPC_HOST");
String weaviateApiKey = System.getenv("WEAVIATE_API_KEY");
String cohereApiKey = System.getenv("COHERE_API_KEY");

WeaviateClient client =
    WeaviateClient.connectToCustom(config -> config.scheme("https") // Corresponds to http_secure=True and grpc_secure=True
        .httpHost(httpHost)
        .httpPort(443)
        .grpcHost(grpcHost)
        .grpcPort(443)
        .authentication(Authentication.apiKey(weaviateApiKey))
        .setHeaders(Map.of("X-Cohere-Api-Key", cohereApiKey)));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources
```

**C#**

```csharp
// Best practice: store your credentials in environment variables
string httpHost = Environment.GetEnvironmentVariable("WEAVIATE_HTTP_HOST");
string grpcHost = Environment.GetEnvironmentVariable("WEAVIATE_GRPC_HOST");
string weaviateApiKey = Environment.GetEnvironmentVariable("WEAVIATE_API_KEY");
string cohereApiKey = Environment.GetEnvironmentVariable("COHERE_API_KEY");

WeaviateClient client = await WeaviateClientBuilder
    .Custom(
        restEndpoint: httpHost,
        restPort: "443",
        grpcEndpoint: grpcHost,
        grpcPort: "443",
        useSsl: true
    )
    .WithCredentials(Auth.ApiKey(weaviateApiKey))
    .WithHeaders(new Dictionary<string, string> { { "X-Cohere-Api-Key", cohereApiKey } })
    .BuildAsync();

var isReady = await client.IsReady();
Console.WriteLine(isReady);
```

## OIDC authentication

OIDC lets you authenticate to a self-hosted Weaviate instance using a bearer access token issued by your identity provider (Keycloak, Okta, Azure AD, Auth0, etc.). Your application obtains the token from the IdP, then passes it to the Weaviate client and the client attaches it to every request.

For server-side configuration (enabling OIDC on Weaviate), the supported authentication flows (client credentials, resource owner password, hybrid), and how to obtain tokens from your IdP, see the [OIDC configuration guide](https://docs.weaviate.io/deploy/configuration/oidc).

> [!WARNING]
>
> Connecting to Weaviate Cloud (WCD) using OIDC is deprecated and should not be used. Please use [API key authentication](https://docs.weaviate.io/cloud/manage-clusters/connect#connect-with-an-api-programmatically) instead.

The examples below assume you already have a bearer access token. Set the following environment variables before running them:

- `WEAVIATE_HTTP_HOST`: host:port of the Weaviate REST endpoint (e.g., `localhost:8080`)
- `WEAVIATE_GRPC_HOST`: host:port of the Weaviate gRPC endpoint (e.g., `localhost:50051`)
- `WEAVIATE_OIDC_ACCESS_TOKEN`: the access token from your IdP
- `WEAVIATE_OIDC_REFRESH_TOKEN`: *(optional)* refresh token for automatic renewal
- `WEAVIATE_OIDC_EXPIRES_IN`: *(optional)* token lifetime in seconds

**Python**

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

# Connect to a self-hosted Weaviate instance configured with OIDC.
# Obtain the access token from your identity provider before connecting.
client = weaviate.connect_to_custom(
    http_host="localhost",
    http_port=8580,
    http_secure=False,
    grpc_host="localhost",
    grpc_port=50551,
    grpc_secure=False,
    auth_credentials=Auth.bearer_token(
        access_token=os.environ["WEAVIATE_OIDC_ACCESS_TOKEN"],
        refresh_token=os.environ.get("WEAVIATE_OIDC_REFRESH_TOKEN"),
        expires_in=int(os.environ.get("WEAVIATE_OIDC_EXPIRES_IN", "60")),
    ),
)
```

**JavaScript/TypeScript**

```ts
import weaviate, { WeaviateClient } from '@weaviate/node';

// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
const client = await weaviate.connectToCustom({
  httpHost: 'localhost',
  httpPort: 8580,
  httpSecure: false,
  grpcHost: 'localhost',
  grpcPort: 50551,
  grpcSecure: false,
  authCredentials: new weaviate.AuthAccessTokenCredentials({
    accessToken: process.env.WEAVIATE_OIDC_ACCESS_TOKEN!,
    refreshToken: process.env.WEAVIATE_OIDC_REFRESH_TOKEN,
    expiresIn: Number(process.env.WEAVIATE_OIDC_EXPIRES_IN ?? 60),
  }),
});
```

**Go (v5)**

```go
// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
cfg := weaviate.Config{
    Host:   os.Getenv("WEAVIATE_HTTP_HOST"),
    Scheme: "http",
    AuthConfig: auth.BearerToken{
        AccessToken:  os.Getenv("WEAVIATE_OIDC_ACCESS_TOKEN"),
        RefreshToken: os.Getenv("WEAVIATE_OIDC_REFRESH_TOKEN"),
        ExpiresIn:    60,
    },
}
client, err := weaviate.NewClient(cfg)
if err != nil{
    fmt.Println(err)
}
```

**Go (v6)**

```go
// Coming soon
```

**Java**

```java
// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
String accessToken = System.getenv("WEAVIATE_OIDC_ACCESS_TOKEN");
String refreshToken = System.getenv("WEAVIATE_OIDC_REFRESH_TOKEN");
long expiresIn = Long.parseLong(
    System.getenv().getOrDefault("WEAVIATE_OIDC_EXPIRES_IN", "60"));

WeaviateClient client = WeaviateClient.connectToCustom(config -> config
    .scheme("http")
    .httpHost("localhost")
    .httpPort(8580)
    .grpcHost("localhost")
    .grpcPort(50551)
    .authentication(Authentication.bearerToken(accessToken, refreshToken, expiresIn)));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources
```

**C#**

```csharp
// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
var accessToken = Environment.GetEnvironmentVariable("WEAVIATE_OIDC_ACCESS_TOKEN")!;
var refreshToken = Environment.GetEnvironmentVariable("WEAVIATE_OIDC_REFRESH_TOKEN") ?? "";
var expiresIn = int.Parse(Environment.GetEnvironmentVariable("WEAVIATE_OIDC_EXPIRES_IN") ?? "60");

WeaviateClient client = await WeaviateClientBuilder
    .Custom(
        restEndpoint: "localhost",
        restPort: "8580",
        grpcEndpoint: "localhost",
        grpcPort: "50551",
        useSsl: false,
        credentials: Auth.BearerToken(accessToken, expiresIn, refreshToken)
    )
    .BuildAsync();

var isReady = await client.IsReady();
Console.WriteLine(isReady);
```
