Application Development

December 19 , 2023 by Shane Connelly

Vectara Roles

Before getting too far into user management in Vectara, you should first understand the different types of user-like objects and how Vectara handles roles and permissions for them.

Vectara has 3 different types of user-like objects:

• Create users when you want to give a specific real person the ability to interact with Vectara, including creating their own API access
• OAuth applications are treated exactly like users internally so they can do anything users can but are used for programmatic access
• Finally, API Keys can be used to grant read/write access to specific corpora but nothing else today

We’ve talked about Vectara’s API keys in a previous blog post, but in this blog post we’re going to dive into users specifically.  Vectara has 4 primary roles for users:

1. Account Admins can manage most elements of the account, including adding and removing additional users but cannot see bills and manage payment details
2. Corpus Admins can manage corpora but can’t add or remove additional users
3. Billing Admins can see bills and manage payment details, but can’t add or remove users or corpora
4. Finally, Account Owners are super-admins that can do everything that Account Admins can do and can also designate Billing Admins.  If you’ve registered for a Vectara account yourself, you’re an Account Owner

Users are associated with an e-mail address, and you can invite them to your account in the Team Management section of the Console.

Given the importance of Corpora for data management, Corpus Admins are particularly important and useful: if you go to the “Access Control” of any given corpus, you’ll see something like the following:

We can see that for each corpus, there’s a Corpus Owner as well as, potentially, Account Admins, API keys, and OAuth applications/users that may all have access to the corpus in different capacities.

User Management APIs

Now that you have a bit more information on users in Vectara, let’s look at how you can manage them via APIs.

Most of the actions you’d take to administer users happen in the ManageUser API.  This API lets you add and delete users, enable and disable them, reset their password, and edit roles.  In the future, we’ll split these out into separate APIs, but for now, you can access them all through the same endpoint.  For a realistic situation, let’s say you want to onboard a new user to your Vectara account.  To do that for our user johndoe:

{
 "userAction": [
   {
     "user": {
       "handle": "johndoe",
       "type": "USER_TYPE__USER",
       "email": "johndoe@foobar.com"
     },
     "userActionType": "USER_ACTION_TYPE__ADD"
   }
 ]
}

One interesting thing you’ll notice here is that you can add multiple users at the same time by simply adding additional “user” objects into the userAction array.  So if you want to invite your whole team, you can do so with a single request!

Once a user joins your team, you’ll be able to list them now using the new ListUsers API and again, you can enable/disable/remove them programmatically with the ManageUser API.  To enable, disable, delete, or reset a user’s password, only a user ID is needed.  For example:

{
 "userAction": [
   {
     "user": {
       "id": 1234
     },
     "userActionType": "USER_ACTION_TYPE__RESET_PASSWORD"
   }
 ]
}

So now, when you provision a new user into your application, you can create API keys for that user as needed but also create and manage users programmatically for those who need direct access to Vectara.

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.