API key management

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.

Assigning the wrong permissions, or using a key 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.

Note

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:

• Assign the right API and resource permissions for your use case
• 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 permissions and recommended usage

Create a personal API key with api_key_role: personal. For scoped API keys, assign the required customer-level api_roles, corpus-specific corpus_roles, and agent-specific agent_roles. The legacy api_key_role values serving and serving_and_indexing are deprecated for creating keys.

API key configuration	Allowed operations	Scope	Recommended usage
Personal API key	Inherits the creating user's permissions	The resources available to that user	Development, testing, and administrative work performed as that user
API key with query permissions	Operations granted by its assigned query roles	Resources named by its role assignments	Applications that only need query access
API key with indexing and query permissions	Operations granted by its assigned indexing and query roles	Resources named by its role assignments	Protected backend ingestion and query workloads

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 keys or keys with indexing permissions 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.

caution

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.

API keys with query permissions

Assign only the query roles and resource-specific roles the application needs. A query-scoped key cannot modify resources unless one of its assigned roles also grants a write operation. Treat a key embedded in browser or mobile code as visible to the end user and restrict its permissions accordingly.

API keys with indexing and query permissions

Assign indexing and query roles only to protected backend workloads that need both capabilities. Because these keys can modify indexed data, treat them like passwords and do not expose them in browser or mobile code.

important

In terms of billing, account owners are responsible for charges incurred through anonymous access to your account with any of these API keys.

warning

🔒 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.

Vectara API endpoints and required API key permissions

This table lists the endpoints, HTTP methods, their summary, and the API key permission profile required for each.

tip

A personal API key has the same permissions as its owner. Whether it can call an endpoint therefore depends on that user's assigned roles.

Method	Path	Summary	Required permission profile
POST	/v2/corpora	Create a corpus	Personal API key
GET	/v2/corpora	List corpora	API key with query permissions, Personal API key
GET	/v2/corpora/{corpus_key}	Retrieve metadata about a corpus	API key with query permissions, Personal API key
DELETE	/v2/corpora/{corpus_key}	Delete a corpus and all its data	Personal API key
PATCH	/v2/corpora/{corpus_key}	Update a corpus	Personal API key
POST	/v2/corpora/{corpus_key}/reset	Remove all documents and data in a corpus	Personal API key
POST	/v2/corpora/{corpus_key}/replace_filter_attributes	Replace the filter attributes of a corpus	Personal API key
POST	/v2/corpora/{corpus_key}/compute_size	Compute the current size of a corpus	Personal API key
POST	/v2/corpora/{corpus_key}/upload_file	Upload a file to the corpus	Personal API key
POST	/v2/corpora/{corpus_key}/documents	Add a document to a corpus	Personal API key
GET	/v2/corpora/{corpus_key}/documents	List the documents in the corpus	API key with query permissions, Personal API key
DELETE	/v2/corpora/{corpus_key}/documents/{document_id}	Delete a document	Personal API key
GET	/v2/corpora/{corpus_key}/documents/{document_id}	Retrieve a document	API key with query permissions, Personal API key
PATCH	/v2/corpora/{corpus_key}/documents/{document_id}	Update document, merging the metadata.	Personal API key
PUT	/v2/corpora/{corpus_key}/documents/{document_id}/metadata	Replace the document metadata.	API key with indexing and query permissions, Personal API key
POST	/v2/corpora/{corpus_key}/documents/{document_id}/summarize	Summarize a document	Personal API key
GET	/v2/corpora/{corpus_key}/query	Simple Single Corpus Query	API key with query permissions, Personal API key
POST	/v2/corpora/{corpus_key}/query	Advanced Single Corpus Query	API key with query permissions, Personal API key
POST	/v2/query	Multiple Corpora Query	API key with query permissions, Personal API key
GET	/v2/queries/{query_id}	Get a query history	API key with query permissions, Personal API key
GET	/v2/queries	List the history of previous queries	API key with query permissions, Personal API key
POST	/v2/chats	Start a chat	API key with indexing and query permissions, Personal API key
GET	/v2/chats	List chats	API key with query permissions, Personal API key
GET	/v2/chats/{chat_id}	Get a chat	API key with query permissions, Personal API key
DELETE	/v2/chats/{chat_id}	Delete a chat	Personal API key
POST	/v2/chats/{chat_id}/turns	Create a new turn in the chat	API key with indexing and query permissions, Personal API key
GET	/v2/chats/{chat_id}/turns	List turns in a chat	API key with query permissions, Personal API key
GET	/v2/chats/{chat_id}/turns/{turn_id}	Get a turn	API key with query permissions, Personal API key
DELETE	/v2/chats/{chat_id}/turns/{turn_id}	Delete a turn	Personal API key
PATCH	/v2/chats/{chat_id}/turns/{turn_id}	Update a turn	API key with indexing and query permissions, Personal API key
POST	/v2/llms	Create an LLM	API key with indexing and query permissions, Personal API key
GET	/v2/llms	List LLMs	API key with query permissions, Personal API key
GET	/v2/llms/{llm_id}	Get an LLM	API key with query permissions, Personal API key
DELETE	/v2/llms/{llm_id}	Delete an LLM	Personal API key
POST	/v2/llms/chat/completions	Creates a model response for the given chat conversation	API key with indexing and query permissions, Personal API key
GET	/v2/generation_presets	List generation presets	API key with query permissions, Personal API key
POST	/v2/evaluate_factual_consistency	Evaluate factual consistency	Personal API key
POST	/v2/encoders	Create an encoder	API key with indexing and query permissions, Personal API key
GET	/v2/encoders	List encoders	API key with query permissions, Personal API key
GET	/v2/rerankers	List rerankers	API key with query permissions, Personal API key
GET	/v2/table_extractors	List supported table extractors	API key with query permissions, Personal API key
GET	/v2/hallucination_correctors	List hallucination correctors	API key with query permissions, Personal API key
POST	/v2/hallucination_correctors/correct_hallucinations	Corrects hallucinations in generated text based on source documents	Personal API key
GET	/v2/jobs	List jobs	API key with query permissions, Personal API key
GET	/v2/jobs/{job_id}	Get a job by ID	API key with query permissions, Personal API key
POST	/v2/users	Create a user in the current customer account	Personal API key
GET	/v2/users	List users in the account	Personal API key
GET	/v2/users/{username}	Get a user	Personal API key
PATCH	/v2/users/{username}	Update a user	Personal API key
DELETE	/v2/users/{username}	Delete a user	Personal API key
POST	/v2/users/{username}/reset_password	Reset the password for a user	Personal API key
POST	/v2/api_keys	Create an API key	Personal API key
GET	/v2/api_keys	List API keys	Personal API key
GET	/v2/api_keys/{api_key_id}	Get an API key	Personal API key
PATCH	/v2/api_keys/{api_key_id}	Update an API key	Personal API key
DELETE	/v2/api_keys/{api_key_id}	Delete an API key	Personal API key
POST	/v2/app_clients	Create an App Client	API key with indexing and query permissions, Personal API key
GET	/v2/app_clients	List App Clients	API key with query permissions, Personal API key
GET	/v2/app_clients/{app_client_id}	Get an App Client	API key with query permissions, Personal API key
PATCH	/v2/app_clients/{app_client_id}	Update an App Client	API key with indexing and query permissions, Personal API key
DELETE	/v2/app_clients/{app_client_id}	Delete an App Client	Personal API key
POST	/oauth/token	Request an access token	Personal API key
POST	/v2/agents	Create new agents	API key with indexing and query permissions, Personal API key
GET	/v2/agents	List agents with filtering and pagination	API key with query permissions, Personal API key
GET	/v2/agents/{agent_key}	Retrieve specific agent configuration	API key with query permissions, Personal API key
PATCH	/v2/agents/{agent_key}	Update agent configuration	API key with indexing and query permissions, Personal API key
DELETE	/v2/agents/{agent_key}	Remove agents	Personal API key
POST	/v2/agents/{agent_key}/sessions	Create agent sessions	API key with indexing and query permissions, Personal API key
GET	/v2/agents/{agent_key}/sessions	List agent sessions	API key with query permissions, Personal API key
GET	/v2/agents/{agent_key}/sessions/{session_key}	Retrieve session details	API key with query permissions, Personal API key
PATCH	/v2/agents/{agent_key}/sessions/{session_key}	Update session metadata	API key with indexing and query permissions, Personal API key
DELETE	/v2/agents/{agent_key}/sessions/{session_key}	Remove sessions	Personal API key
POST	/v2/agents/{agent_key}/sessions/{session_key}/events	Create conversation events (input only)	API key with indexing and query permissions, Personal API key
GET	/v2/agents/{agent_key}/sessions/{session_key}/events	List session events	API key with query permissions, Personal API key
GET	/v2/agents/{agent_key}/sessions/{session_key}/events/{event_id}	Retrieve specific events	API key with query permissions, Personal API key
POST	/v2/tool_servers	Register MCP servers	API key with indexing and query permissions, Personal API key
GET	/v2/tool_servers	List registered servers	API key with query permissions, Personal API key
GET	/v2/tool_servers/{tool_server_id}	Retrieve server details	API key with query permissions, Personal API key
PATCH	/v2/tool_servers/{tool_server_id}	Update server configuration	API key with indexing and query permissions, Personal API key
DELETE	/v2/tool_servers/{tool_server_id}	Remove servers	Personal API key
POST	/v2/tool_servers/{tool_server_id}/sync	Synchronize server tools	API key with indexing and query permissions, Personal API key
GET	/v2/tools	List available tools	API key with query permissions, Personal API key
GET	/v2/tools/{tool_id}	Retrieve tool specifications	API key with query permissions, Personal API key
PATCH	/v2/tools/{tool_id}	Update tool configuration	API key with indexing and query permissions, Personal API key
DELETE	/v2/tools/{tool_id}	Remove tools	Personal API key
POST	/v2/instructions	Create behavioral instructions	API key with indexing and query permissions, Personal API key
GET	/v2/instructions	List instructions with filtering	API key with query permissions, Personal API key
GET	/v2/instructions/{instruction_id}	Retrieve instruction details	API key with query permissions, Personal API key
PATCH	/v2/instructions/{instruction_id}	Update instruction templates	API key with indexing and query permissions, Personal API key
DELETE	/v2/instructions/{instruction_id}	Remove instructions	Personal API key
POST	/v2/instructions/{instruction_id}/test	Test instruction compilation	API key with indexing and query permissions, Personal API key
DELETE	/v2/instructions/{instruction_id}/versions/{version}	Remove specific instruction versions	Personal API key

Create an API key

You can create a Personal API key or a scoped API key, then pass the secret in the x-api-key header when issuing requests.

Use an API key

To use an API key, pass its secret in the x-api-key request header.

JavaScript

CODE EXAMPLE

Code example with py syntax.py

1

Python

CODE EXAMPLE

Code example with js syntax.js

1

cURL

CODE EXAMPLE

Code example with curl syntax.curl

1

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 a query-scoped key	The key lacks an indexing role	Assign the required indexing role to a backend key
Personal key used in browser	The key inherits the user's permissions and is exposed to the client	Use a minimally scoped key and assume client-side credentials are visible

Disable, enable, and delete API keys

To temporarily disable access to an API key, navigate to the API keys 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 a scoped 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.

Important

• 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 you delete a scoped API key, you cannot undelete it. All external systems that use the key will be blocked.

Next Steps

• Set Up Account and Corpus Permissions (RBAC)
• Apply Metadata Filters for Attribute-Based Access Control (ABAC)