Create and Use API Keys
API Keys enable controlled, anonymous access to several administrative tasks, indexing your data, and running semantic searches on your corpora—handy for platform admins setting up systems or app developers integrating public-facing websites. This greatly simplifies integration from public-facing systems like websites.
Selecting the wrong key type, or using it incorrectly, can result in errors or expose your system to unnecessary risk. If a key is compromised, you can quickly revoke the key and replace it in minutes.
If you create a new corpus, generate a new API key to access its data. You will not be able to access it with existing API keys. Existing keys are bound to their original corpus.
This guide helps you:
- Select the right key type for your use case, whether admin or app-focused
- Avoid permission errors tied to scoping or misuse
- Secure your credentials properly
Prerequisites
- Access to the Vectara Console
- Have at least one corpus
- Admin or Indexing privileges on the corpus
API key types and recommended usage
API Key Type | Key Prefix | Allowed Operations | Scope | Recommended Usage |
---|---|---|---|---|
Personal Key | zut_ | All user-level operations | Account-wide | Admin tasks, Developers for testing, internal scripts |
Query Key | zqt_ | Read-only search | Corpus-specific | Developers for public-facing search, front-end apps |
Index Key | zwt_ | Index and query | Corpus-specific | Developers for ingestion and server-side testing |
Best practices
- ✅ Use unique keys per use case or microservice
- ✅ Apply the principle of least privilege by assigning the minimal set of permissions needed to accomplish your goal
- 🔄 Rotate API keys periodically and revoke unused ones
- 🔒 Never embed Personal or Index keys in client-side code. Store them on your server instead.
Personal API key
The Personal API Key helps developers in early stages of exploration and prototyping with Vectara, or platform admins setting up initial configurations. This method provides a straightforward getting started experience for integrating accounts with external applications without the complexity of OAuth authentication. You can use the Personal API Key when putting together a quick prototype, or if you are working on an integration that does not yet support OAuth 2.0.
Supported actions: Creating, deleting, and listing corpora, managing API keys for accessible corpora, reading usage data, updating corpora filters, executing queries, and indexing.
Unsupported actions: Deleting an account, validating a registration, transferring account ownership, deleting users, or accessing billing data.
A Personal API Key inherits the permissions of its associated user account. For example, a key generated by a billing admin will only possess billing admin-related permissions. Because of their broad access, treat Personal API Keys with the same caution as passwords.
Query API keys
We recommend Query API keys for read-only querying operations and for developers embedding in code that runs in potentially insecure environments like web browsers or mobile apps. Query API Keys provide the least amount of risk because they have a limited scope and do not modify account data.
Index API keys
Index API Keys offer a practical solution for Developers and ML Engineers needing read and write access during development and testing phases. Because they also provide write access, Index API Keys are more powerful than Query API Keys and should be treated like passwords and used with caution in production environments.
In terms of billing, account owners are responsible for charges incurred through anonymous access to your account with any of these API keys.
🔒 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.
Create an API key
You can easily create a Personal API key or an Index or Query API Key, and then simply embed the API key and directly pass it to Vectara when issuing requests.
Use an API key
To use a Personal, Index, or Query API key, pass it using the x-api-key
header request.
- JavaScript
- Python
- cURL
api_key_header = { "x-api-key": API_KEY } data_dict = { "query": [ { query: "What is the meaning of life?", search: { corpora: [{ corpus_key: corpus_key }], offset: 0, limit: 10, }, } ] } ] } payload = json.dumps(data_dict) response = requests.post( "https://undefined/v1/query", data=payload, verify=True, headers=api_key_header)
fetch("https://undefined:443/v2/query", { headers: { "Content-Type": "application/json", "x-api-key": api_key, }, body: JSON.stringify({ query: [ { query: "What is the meaning of life?", search: { corpora: [{ corpus_key: corpus_key }], offset: 0, limit: 10, }, ], }), method: "post", }) .then((res) => res.json()) .then((data) => console.log(data)) .catch((error) => console.log(error));
curl -X POST \ -H "x-api-key: ${API_KEY}" \ -H "customer-id: ${CUSTOMER_ID}" \ https://undefined:443/v1/query \ -d @- <<END; { "query": [ { "query": "What is the meaning of life?", search: { corpora: [{ corpus_key: corpus_key }], offset: 0, limit: 10, } ] } END
Common issues and how to resolve them
Issue | Cause | Fix |
---|---|---|
403: Permission Denied | Key not scoped to corpus | Recreate key with correct corpus_key |
401: Unauthorized | Invalid or missing key in header | Ensure x-api-key is correctly included |
Indexing fails with Query key | Used wrong key type | Use Index (zwt_ ) or Personal (zut_ ) key |
Personal key used in browser | Security vulnerability | Use Query key for public search apps |
Disable, enable, and delete API keys
To temporarily disable access to an API key, navigate to the Authorization tab.
Disable a personal API key
Click the Actions drop-down and select Disable. You can also regenerate the Personal API key from this menu.
Disable an index or query API key
Click the drop-down menu and select Disable. This menu also lets you copy, delete, and reenable the API key.
It will take around a minute for query requests using this key to be blocked.
- Once you disable an API key, you can enable it again through same action menus. It can take a couple minutes before it can serve query traffic again.
- Once delete an index or query API key, you cannot undelete it. All external systems that issue queries using the key will be blocked.