Security
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.
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.
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.
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.
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.
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
- Python
- cURL
Code Example
Code example with py syntax.1
Code Example
Code example with js syntax.1
Code Example
Code example with curl syntax.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.
- 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
- Build an embedded agent with a widget connector — a walkthrough that keeps provisioning credentials out of the browser embed.
- Set Up Account and Corpus Permissions (RBAC)
- Apply Metadata Filters for Attribute-Based Access Control (ABAC)