API Keys

API Keys allow controlled, anonymous access to running semantic searches on your corpora. This greatly simplifies integration from public-facing systems such as websites, by allowing them to embed the API key and directly pass it to Vectara when issuing requests. Should a key be compromised, it can be revoked in minutes, and a new key issued.

info

Account owners are responsible for charges incurred through anonymous access to your account with an API key.

Administrative actions cannot be performed through these keys.

The remainder of this guide walks you through managing and using the API Keys.

Create an API Key

If you have the necessary permissions you'll see the API Keys in the sidebar. Click on it and you'll see the following page

Click the Create Key button to create a new key, the following dialog will display:

Enter the name of the key and select the corpora you want to be able to query using the it. Then, click Create.

You can now start using the key.

danger

🔒 Always keep your API Keys and OAuth tokens private. Do not share them through email, Slack, Discord, forums, or other public channels because it can lead to unauthorized access. Treat these keys with the same confidentiality as your personal credentials.

Use an API Key

To use an API key, pass it using the x-api-key header request.

JavaScript

api_key_header = {
    "customer-id": CUSTOMER_ID,
    "x-api-key": API_KEY
}
 
data_dict = {
    "query": [
        {
            "query": "What is the meaning of life?",
            "num_results": 10,
            "corpus_key": [
                {
                    "customer_id": CUSTOMER_ID,
                    "corpus_id": CORPUS_ID
                }
            ]
        }
    ]
}
payload = json.dumps(data_dict)
response = requests.post(
    "https://api.vectara.io/v1/query",
    data=payload,
    verify=True,
    headers=api_key_header)

Python

fetch("https://api.vectara.io:443/v1/query", {
  headers: {
    "Content-Type": "application/json",
    "x-api-key": api_key,
    "customer-id": customer_id,
  },
  body: JSON.stringify({
    query: [
      {
        query: "What is the meaning of life?",
        num_results: 10,
        corpus_key: [{ customer_id: customer_id, corpus_id: corpus_id }],
      },
    ],
  }),
  method: "post",
})
  .then((res) => res.json())
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

cURL

curl -X POST \
  -H "x-api-key: ${API_KEY}" \
  -H "customer-id: ${CUSTOMER_ID}" \
  https://api.vectara.io:443/v1/query \
  -d @- <<END;
  {
    "query": [
      { "query": "What is the meaning of life?",
        "num_results": 10,
        "corpus_key": [{"customer_id": ${CUSTOMER_ID}, "corpus_id": ${CORPUS_ID}}]
      }
    ]
  }
END

Management

This section describes how to manage API keys.

Disable and Enable API Keys

To temporarily disable access to an API key, begin by visiting the API Keys screen. Select disable by clicking on the action menu (three dots) of the key you want to disable.

It will take around a minute for query requests using this key to be blocked.

Once disabled, a key can be reenabled through the action menu. It will take a minute or two before it can serve query traffic again.

Delete API Keys

A key may be permanently deleted through its action menu. Proceed with caution, once deleted, there is no way to undelete it, and all external systems that issue queries using the key will be blocked.