Choose authentication method
Vectara supports two main methods for authenticating API requests: API keys and OAuth 2.0 tokens. Choosing the right one depends on where and how your application or team interacts with Vectara’s APIs, whether you are a Developer prototyping or a Platform Admin securing operations.
We recommend that you use OAuth 2.0 to authenticate API requests in production. It offers better security, auditability, and access management compared to API keys.
This guide helps you select the best method based on:
- Your architecture (frontend, backend, serverless)
- Your security needs (short-lived vs long-lived credentials)
- Your use case (querying, indexing, or admin tasks)
Authentication method selection
The following table compares API Keys and OAuth 2.0, highlighting key features and scenarios to guide your choice, whether you are a Developer experimenting with APIs or an Admin configuring secure access:
| Scenario | Recommended Method | Why This Works | Workflows |
|---|---|---|---|
| Explore the API or prototype | ✅ Personal API key | Simplest setup Inherits the creating user's permissions. | A Developer tests ingestion in a sandbox; an Admin creates corpora for setup. |
| Build a public search UI | ✅ API key with query permissions | Limit the key to the required query and corpus permissions. | An App Developer embeds search in a help center for End Users to browse FAQs. |
| Index documents securely from a backend | ✅ API key with indexing and query permissions | Enables the required indexing and querying operations when assigned those permissions. | An ML Engineer indexes CMS data for RAG optimization in a secure environment. |
| Control client roles in production | ✅ OAuth 2.0 Token (JWT) | Role-based, expiring tokens (30 min) Ideal for service-to-service access. | A Dev Team Lead deploys a microservice querying corpora with user-specific roles. |
| Automate token rotation | ✅ OAuth 2.0 Token (JWT) | Built-in expiration reduces risk of long-lived credentials. | An Admin automates secure workflows for Client Apps. |
| Prevent accidental key leaks | ✅ OAuth 2.0 Token (JWT) | Short-lived tokens are harder to misuse Detectable by security tools. | A Client App serves End Users with minimal exposure risk. |
| Access APIs beyond indexing/querying (administration tasks) | ✅ OAuth 2.0 Token (JWT) | Supports broader permissions (such as corpus creation) with role-based control. | An Admin manages API keys or corpora via secure tokens. |
| Secure backend server access | ✅ API Key (Server) or ✅ OAuth 2.0 | API keys work if secured OAuth expiring tokens are safer for production. | A Developer runs a backend service accessing corpora securely. |
| Use in browser/client-side code | ✅ API key with query permissions | Limit the key to the minimum required query and corpus permissions. | A Developer builds a public UI for End Users to query a help center. |
| Fine-grained access scopes | ✅ OAuth 2.0 Token (JWT) or an API key with assigned roles | Both support API-level and resource-specific role assignments. | A Dev Team Lead sets precise access for a Client App; an Admin configures roles. |
| Safe for long-term production use | ✅ OAuth 2.0 Token (JWT) ⚠️ API Keys: Use with care, rotate manually | OAuth expiring tokens are safer, reducing exposure risk. | An Admin ensures long-term security for Client Apps; a Developer deploys safely. |
Authentication methods by use case
Prototyping or admin tasks
- Use: Personal API Key
- Why: Inherits your user account’s permissions and works across all accessible corpora.
- Example: A Platform Admin creating corpora or a Developer testing ingestion in development.
Never use Personal API keys in a production system. They have broad access and should be treated like passwords. Admins must avoid this risk in live systems.
Public-facing query interface
- Use: API key with query permissions
- Why: Assign only the required query and corpus permissions.
- Example: An App Developer adding search to a marketing website or help center.
Ideal for usage in web or mobile apps when security is scoped and no indexing is required.
Secure indexing and backend workloads
- Use: API key with indexing and query permissions
- Why: Assign the required indexing and query permissions. Use the key only in secure backend services.
- Example: An ML Engineer optimizing RAG by indexing data from an internal CMS.
Do not expose index keys to browser-based clients. Treat them as secrets.
Production-grade security and role control
- Use: OAuth 2.0 (JWT Token)
- Why: Scoped, expiring tokens managed by app clients. Best for services and third-party apps.
- Example: A Dev Team Lead deploying a microservice that queries corpora based on user roles.
Use OAuth to:
- Limit access by role (query/index/admin)
- Automatically expire and rotate tokens
- Enforce strong isolation between clients
- Build integrations that follow security best practices