Authentication methods and authorization levels
Vectara has robust authentication and authorization methods in place to secure your data and operations, whether you are an Admin configuring the system or tenant, a developer building applications for your enterprise, or an end user issuing queries through an application. We provide a structured authentication and authorization model to control access to our platform and your data.
This overview introduces the supported mechanisms and access control levels, helps you understand what is platform-enforced versus application-enforced, and provides a quick reference to help answer key questions for internal discussions.
Authentication methods in Vectara
Vectara supports two authentication strategies:
- API Keys – Lightweight tokens for direct API access, often used for quick prototyping or front-end queries.
- OAuth 2.0 Tokens – Expiring JWT tokens generated by app clients, suited for secure production environments.
Use the following table to understand the key types, whether you develop applications and test APIs, or a platform admin configuring systems or managing corpora.
| API Key Type | Key Prefix | Allowed Operations | Access Scope | Intended Use |
|---|---|---|---|---|
| Personal API Key | zut_... | All operations, with some limitations such as not deleting your account or creating users | Account-wide (inherits user’s permissions) | Administrative tasks, prototyping, full access across corpora |
| Query API Key | zqt_... | Read-only search operations | Corpus-specific | Front-end applications, public-facing query requests |
| Index API Key | zwt_... | Read and write (indexing and querying) | Corpus-specific | Server-side indexing and querying |
| OAuth 2.0 Token | (JWT token) | Scoped by roles granted to OAuth client | Account or corpus scope | Secure production authentication, third-party integrations |
See Choosing the Right Authentication Method to decide whether to use API keys or OAuth based on your use case.
Authorization levels in Vectara
Vectara primarily enforces authorization at the account and corpus level through Role-Based Access Control (RBAC), critical for Admins managing users on the Vectara Platform, or Developers scoping corpus access. You can layer Attribute-Based Access Control (ABAC) by applying metadata-based filters at query time. Let's explore the various authorization levels to help you implement secure access control.
Account administration roles
These roles enable you to define administrators. For example, by assigning someone Owner or Account Admin permissions in the Console, they will have broad control over the platform’s data and user access. But by not assigning them Billing Admin permissions, they will be restricted from accessing billing data.
How it works: Vectara assigns account-level roles (Owner, Account Admin, Billing Admin) to grant full administrative access. Owners have unrestricted control, including account deletion, while Account Admins manage corpora and users (excluding billing). Billing Admins focus solely on billing tasks. These roles do not allow direct access to document contents.
Supported mechanisms: RBAC with predefined roles, managed by admins through the Console.
Limitations: Fully supported with no restrictions, but roles do not provide granular document access. Use corpus-level roles.
Corpus access management
Limit access to corpora by assigning roles like Query (QRY), Index (IDX), or Admin (ADM) per corpus, scoping API keys or OAuth tokens to specific corpora via the Console. For example, a developer can assign a Query role to an API key for read-only access to a marketing corpus, ensuring isolated, secure data interactions.
How it works: Corpus-level roles—QRY for read-only searches, IDX for write and
query, and ADM for full control—are assigned per corpus. API keys (zqt_, zwt_)
or OAuth tokens are scoped to individual corpora, preventing cross-corpus access
unless explicitly granted.
Supported mechanisms: RBAC with QRY, IDX, and ADM roles, configurable by admins.
Limitations: Fully supported and the primary method for data segmentation. This is ideal for secure, isolated access.
Coarse-grained (document-level) access control
Restrict document access within a shared corpus by applying metadata filters
at query time, ensuring End Users see only their authorized data. For example,
a developer can configure a client app to filter HR documents so only a
specific user sees their records (user_id = user123), implementing
document-level isolation.
How it works: Since Vectara does not currently support native document-level
ACLs, you apply metadata filters at query time (metadata_filter: "user_id = X")
to implement isolation. Client Apps, coded by developers, enforce these filters
to restrict visibility based on metadata like user_id or team.
Supported mechanisms: ABAC with metadata filters, implemented at the application level.
Limitations: Not platform-enforced and relies on app logic. Users with Query access could bypass filters if misused, requiring careful client app design.
Fine-grained (part-level) access control
Control specific document parts (chunks) by segregating sensitive data into restricted corpora or using metadata filters, a critical need for developers securing client apps. For example, a developer can index sensitive fields like salary data in a restricted corpus, accessible only to authorized apps with specific keys.
How it works: Vectara does not natively support part-level ACLs. Instead, you store sensitive parts in a separate, restricted corpus or use metadata filters to obscure them during queries. Anyone with Query (QRY) access to a corpus sees the entire document, so workarounds are critical.
Supported mechanisms: ABAC with metadata filters or corpus segmentation, enforced by the application.
Limitations: Not currently supported and requires careful corpus design or filter logic. Workarounds add complexity for developers.
Multi-tenancy
Isolate tenant data by dedicating a corpus per customer or team with scoped API
keys or OAuth tokens, a priority for admins managing enterprise deployments.
For example, an amin can create a corpus (tenant_acme_docs) for Acme Inc.,
ensuring their client app accesses only their data, preventing cross-tenant
exposure.
How it works: Assign each tenant a dedicated corpus with its own API keys or OAuth tokens, managed via the Console. This platform-enforced isolation prevents cross-tenant access. Alternatively, app-enforced filters (ABAC) within a shared corpus are less secure.
Supported mechanisms: Corpus-level RBAC for isolation, with optional ABAC filters for shared corpora.
Limitations: Corpus management adds overhead, but it provides the most secure approach. Filter-based alternatives risk exposure if misconfigured.
Transient data for real-time queries
Query data without permanent storage by indexing it in a temporary corpus or deleting documents post-session using API calls, ideal for end users with sensitive data. For example, an end user can upload a contract for summarization in a client app, which indexes it temporarily, delivers results, and deletes the data afterward.
How it works: Vectara requires data to be indexed in a corpus for querying.
For transient use, create a temporary corpus for the user session and delete it
programmatically with the API, or upload documents, query them, then delete
specific documents. Application logic manages session-based deletion, requiring
Index (zwt_) or Admin (zut_) API keys.
Supported mechanisms: API-driven corpus or document management, using RBAC for Index or Admin roles.
Limitations: Requires custom application logic to detect session end and execute deletion. Ensure API keys are scoped appropriately to avoid unauthorized access.
Next steps
Use the following task guides to implement secure access and authorization: