AI Connector

Last updated October 19, 2026

AI Connector lets you connect apps in your cluster to AI Gateway to work with AI models. The connector creates an API key and automatically saves it in a Kubernetes secret. You can attach the secret to your app as an environment variable or a file.

Requests made with a connector key are billed according to AI Gateway pricing.

Create a Key
Copy link

You can create a key only for a running cluster.

  1. Go to the Kubernetes section and click on the cluster.
  2. Go to the Management tab and click Connect or Change next to AI Connector.
  3. Click Create key.
  4. Enter a name for the key.
  5. In the Expiration field, select a validity period for the key. 
  6. Select one or more namespaces where your apps will use the key.
  7. (Optional) Add a description for the key and select a project. 
  8. Click Create.

A window opens with the key value and the AI Gateway address. 

Save the Key Value
Copy link

Save the key value if you plan to use the key outside the cluster secret. The dashboard shows the key only once.

If you connect your app through a secret, you don’t need to copy the value.

Copy the Secret Name
Copy link

The connector creates an Opaque secret in each selected namespace and stores the key in the api-key field. While the secrets are being created, the key appears as processing in the list. Once the cluster confirms, the key becomes active.

You will need the secret name to configure your app. A key has the same secret name in all selected namespaces.

  1. Go to the Kubernetes section and click on the cluster.
  2. Go to the Management tab and click Change next to AI Connector.
  3. Copy the secret name under the key name.

Track Key Expiration
Copy link

If you set an expiration date when creating a key, AI Gateway stops accepting requests with that key once it expires. The secret stays in the cluster.

The expiration date appears in the connector’s key list. It turns yellow as the date approaches, and red one week before expiration and after it.

  1. Go to the Kubernetes section and click on the cluster.
  2. Go to the Management tab and click Change next to AI Connector.
  3. Check the key expiration date. 

The expiration date turns yellow as the date approaches, and red one week before expiration and after it.

Connect the Key to an App
Copy link

The app and the secret must be in the same namespace. Choose one of two methods, depending on how your app reads the key.

Use an Environment Variable
Copy link

  1. In the container manifest, add a variable to the env section.
  2. In valueFrom.secretKeyRef, specify the secret name and the api-key field.

The key value is passed to the variable your app uses, for example OPENAI_API_KEY.

Use a File
Copy link

  1. Add the secret to the volumes section.
  2. Mount it to the container with volumeMounts.

The key is available in the api-key file inside the mount directory. For example, if you mount the secret to /etc/ai-gateway, your app must read /etc/ai-gateway/api-key.

Set the Base URL
Copy link

In your app settings, set the API base URL to https://ai-api.hostman.com/v1. If your app supports the OPENAI_BASE_URL variable, you can pass the address through it.

Regenerate a Key
Copy link

You manage connector keys in the AI Connector section on the cluster's Management tab. The key also appears on the AI Gateway API keys page, but you can't edit or delete it there.

  1. Go to the Kubernetes section and click on the cluster.
  2. Open the Management tab.
  3. In the AI Connector section, click Change.
  4. Click the three dots next to the key and select Regenerate.
  5. (Optional) Change the list of namespaces. The connector creates the secret in added namespaces and deletes it from removed ones.
  6. Click Regenerate.

If your app gets the key through an environment variable, restart the app pods to pick up the updated secret. For example, for an app deployed with a Deployment, run:

kubectl rollout restart deployment/my-app -n default

Replace my-app and default with your Deployment name and namespace.

The connector writes the new value to the secrets. The secret name stays the same, so you don't need to change the reference in your manifest. The dashboard shows the new key value only once.

Delete a Key
Copy link

Deleting a key revokes it and removes the related secrets from all namespaces. Apps that use the key lose access to AI Gateway.

  1. Go to the Kubernetes section and click on the cluster.
  2. Open the Management tab.
  3. In the AI Connector section, click Change.
  4. Click the three dots next to the key.
  5. Select Delete.
  6. Confirm the action.

Test the Connection
Copy link

This example shows a basic connection to AI Gateway from a cluster. You create a temporary pod with the python:3.12-slim image. A script inside the pod reads the key from the secret, sends a request to the model, and prints the response to the logs. You don't need to install extra packages or build a custom image.

The app and the secret must be in the same namespace. The example uses the default namespace and the ai-key-test-dfffcae0 secret. Replace the secret name with the one you copied from the dashboard.

  1. Create a file named ai-gateway-check.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: ai-gateway-check
  namespace: default
spec:
  restartPolicy: Never
  containers:
    - name: check
      image: python:3.12-slim
      env:
        - name: AI_GATEWAY_API_KEY
          valueFrom:
            secretKeyRef:
              name: ai-key-test-dfffcae0
              key: api-key
      command: ["python", "-c"]
      args:
        - | import json import os import urllib.request 
          payload = json.dumps({
              "model": "openai/gpt-4.1-mini",
              "messages": [{"role": "user", "content": "Answer in one word: is it working?"}],
              "max_tokens": 20,
          }).encode("utf-8")

          request = urllib.request.Request(
              "https://ai-api.hostman.com/v1/chat/completions",
              data=payload,
              headers={
                  "Authorization": "Bearer " + os.environ["AI_GATEWAY_API_KEY"],
                  "Content-Type": "application/json",
              },
          )

          with urllib.request.urlopen(request, timeout=60) as response:
              result = json.load(response)

          print(result["choices"][0]["message"]["content"])

The example uses the openai/gpt-4.1-mini model. If needed, replace it with any model available in the AI Gateway list.

  1. After the key becomes active, check that the secret exists: 

kubectl get secret ai-key-test-dfffcae0 -n default

  1. Create the pod:

kubectl apply -f ai-gateway-check.yaml

  1. Wait for the pod to finish: 

kubectl get pod ai-gateway-check -n default

  1. View the model response in the logs:

kubectl logs ai-gateway-check -n default

If the request succeeds, the pod status changes to Completed and the logs contain the model response.

  1. Delete the pod:

kubectl delete pod ai-gateway-check -n default