Skip to main content
Version: 2.0

Users

The Vectara Python SDK provides methods to manage users in your account, including listing, creating, retrieving, updating, deleting, and resetting passwords. The UsersClient (synchronous) and AsyncUsersClient (asynchronous) support these operations, with options to filter by corpus access, assign roles, and configure timeouts. Usernames must be percent-encoded for API calls.

Note: User management operations require OAuth authentication, not API keys.

Prerequisites

This guide assumes you have a corpus called my-docs. If you haven't created a corpus yet, follow the Quick Start guide to set up your first corpus.

List users​

LIST USERS BY CORPUS ACCESS
1

List all users in the account, optionally filtering by corpus access.

  • corpus_key (str, optional): Filter users with access to this corpus.
  • limit (int, optional): Max number of users per page.
  • page_key (str, optional): Fetch next page of results.
  • request_timeout (int, optional): Timeout in seconds.

Returns:
Iterator of user objects, each with:

  • username
  • email
  • description
  • api_roles
  • enabled

Error handling:

  • 403 Forbidden: Insufficient OAuth permissions.
  • 404 Not Found: Corpus does not exist (if filtering by corpus_key).
  • 500 Internal Server Error: API unavailable.

Create a User​

CREATE A USER WITH ROLES
1

Create a new user with an email, optional username, description, and API roles.

  • email (str): User's email address (required)
  • username (str, optional): Login username (email is default)
  • description (str, optional): Free-form user description
  • api_roles (list[str], optional): Assigned roles (corpus_admin, query_writer)

Returns:
User object with:

  • username
  • email
  • api_roles
  • enabled

Error handling:

  • 400 Bad Request: Missing required fields or invalid email.
  • 409 Conflict: Username or email already exists.
  • 403 Forbidden: Insufficient OAuth permissions.

Retrieve a User​

GET USER DETAILS
1

Get details for a specific user by their username (percent-encoded if needed).

  • username (str): Username, percent-encoded (through urllib.parse.quote())

Returns:
User object with fields:

  • username
  • email
  • api_roles
  • enabled
  • description

Error handling:

  • 404 Not Found: User does not exist.
  • 403 Forbidden: Insufficient OAuth permissions.

Update a User​

UPDATE USER ROLES
1

Update a user’s status or roles, such as enabling/disabling or changing permissions.

  • username (str): Percent-encoded username (required)
  • enabled (bool, optional): Enable or disable user account
  • api_roles (list[str], optional): Update roles
  • description (str, optional): Update user description

Returns:

Updated user object with:

  • username
  • api_roles
  • enabled
  • description

Error handling:

  • 404 Not Found: User does not exist.
  • 403 Forbidden: Insufficient OAuth permissions.
  • 400 Bad Request: Invalid update parameters.

Delete a User​

DELETE A USER
1

Delete a user from the account by their username (percent-encoded).

  • username (str): Percent-encoded username

Returns:

None (success is silent)

Error handling:

  • 404 Not Found: User does not exist.
  • 403 Forbidden: Insufficient OAuth permissions.

Reset a password​

RESET USER PASSWORD
1

Reset a user’s password, sending a reset email to their registered address.

  • username (str): Percent-encoded username

Returns: User object for whom the reset was sent:

  • username
  • email

Error handling:

  • 404 Not Found: User does not exist.
  • 403 Forbidden: Insufficient OAuth permissions.