Application Development
Managing Vectara’s API Keys Programmatically
Vectara has had an ability to manage API keys via the Console, and even allowed indexing API keys for several months, but up until today, we’ve never released this functionality via public APIs.
December 14 , 2023 by Shane Connelly
Today, we’re incredibly excited to announce that we’re announcing the GA release of Vectara’s API Keys capabilities, including our new public APIs to manage these keys.
Background and OAuth vs API Keys
Vectara has had an ability to manage API keys via the Console, and even allowed indexing API keys for several months, but up until today, we’ve never released this functionality via public APIs. As we mentioned in a previous blog post: one of our goals from here on out is to publicly release more APIs for the Vectara platform so that you can build applications more easily on top of Vectara. APIs for API key management are particularly useful for those of you that are building applications for other users: resellers, partners, and even those that just have several departments or groups in your organization that you want to enable with Vectara’s capabilities. With this release, now you can programmatically create, grant, and revoke access to Vectara corpora.
One thing we like to remind Vectara users is that if/where you can use OAuth 2.0 instead of API keys, we would highly encourage you to do so. OAuth 2.0 has a number of features baked into the standard that simply are not present in most API keys. For example, OAuth 2.0 has built-in token expiration so that if you ever inadvertently ended up with a JWT checked into a public git repo, it would be far less likely to be usable by an attacker by the time they discovered the token. It’s for this reason that you currently cannot manage API keys with an API key: you’ll need to do so with an OAuth application or via the console.
Still, API Keys are simple to get started with, and by publicly releasing the API keys to manage them, our hope is that the Vectara community will be able to build even more interesting applications on top of Vectara! So now let’s get into how to make use of the API Key functionality.
Working with Vectara’s API Keys
To create or manage API keys, you can still go to the API Key management page in the Vectara Console, and we’ll use that for now before diving into programmatic access. From there, you can “Create API key” and you’ll notice that API keys can have different types of API access:
Figure 1: Creating a new API key in Vectara
QueryService API keys are read only: they cannot be used to perform any indexing operations on Vectara. These are great for applications that have split the ingest-side from the query side.
If you create a read-only QueryService API key, you’ll notice that it will start with zqt_. Likewise, if you ever see an API key that starts with zqt_ you can immediately know that this API key does not have any access to index documents.
Likewise, if you create an API key that has QueryService & IndexService access, this indicates that the API key is read and write. These API keys will start with zwt_. As a best practice, avoid using write-enabled keys where a read-only key will suffice.
If you want a full overview of how to use Console to manage API keys, see the documentation here.
APIs for API Keys
Now let’s explore the APIs for management of API keys. You can try these all from the API Playground, but to reiterate you’ll need to use an OAuth JWT to actually manage these keys and thus to try them in the API Playground.
With that said, here’s an overview of the APIs that are now available:
- CreateApiKey: Creates a new API key. When you create a new API key, you’ll need to define whether it’s for “Serving” (read-only) or for “Indexing” (read-write). You can give it one or more corpora to be able to access.
- DeleteApiKey: As the name suggests, disables and deletes an API key permanently, rendering it useless.
- EnableApiKey: Takes a Boolean flag (enable) which defines whether the API key should be enabled or disabled. Set to false to disable the API key and vice versa to enable a disabled API key.
- ListApiKeys: List the existing API keys so you can see what keys have access to what corpora, and with what permissions.
With these new APIs, you can now provision new applications to existing corpora as well as enable and disable their access based on your own access rules.
As always, we’d love to hear your feedback! Connect with us on our forums or on our Discord. If you’d like to see what Vectara can offer you for retrieval augmented generation on your application or website, sign up for an account.
