Skip to main content
Version: 2.0

API Keys

The Vectara Python SDK enables you to manage API keys for authenticating API calls, using ApiKeysClient (synchronous) or AsyncApiKeysClient (asynchronous). You can list, create, retrieve, update, or delete API keys, with options to filter by corpus or role and configure timeouts. This section demonstrates common API key management tasks.

Common API Key Operations:

  • List API keys by role or corpus for quick auditing
  • Create new keys with role-based or corpus-level scopes
  • Update or disable keys instantly to protect data
  • Delete keys to immediately revoke API access
  • Use async methods for large-scale, automated environments
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 API Keys​

LIST API KEYS BY CORPUS
1

List API keys in the account, optionally filtering by corpus or role.

  • corpus_key: (Optional) Filter keys that grant access to a specific corpus (recommended for RBAC or zero-trust setups).
  • api_key_role: (Optional) Restrict results to a specific key role, such as 'serving', 'query', or 'admin'.
  • limit: (Optional) Page size—limit the number of keys per request.

Create an API Key​

CREATE AN API KEY
1

Create an API key with a name, role, and optional corpus permissions.

  • name: Human-readable label for the key (recommended for tracking, “CI/CD Pipeline”, “Support App”).
  • api_key_role: Assign a minimum-permission role such as:
    • 'serving': For query/search operations (least privilege for external clients).
    • 'indexing': For document ingestion (do not share externally).
    • 'admin': Full permissions (reserved for trusted backend use).
  • corpus_keys: (Optional) Limit key access to specific corpora for extra isolation—critical for regulated environments.

Retrieve an API Key​

GET API KEY DETAILS
1

Get details for a specific API key by its ID.

  • api_key_id: The identifier for the key to look up.

Returns:

Full metadata for the key, including enabled, role, name, and corpus scopes.

Update an API Key​

UPDATE API KEY STATUS
1

Update an API key’s status (enable/disable).

  • api_key_id: The key to update (rotate or revoke access).
  • enabled: Set to false to disable the key (recommended best practice for temporary revocation instead of deletion).

Delete an API Key​

DELETE AN API KEY
1

Delete an API key to revoke its access and permanently revoke all access—critical after role changes, deprovisioning, or breach response.

  • api_key_id: The key’s unique identifier.

Asynchronous API Key Management​

CREATE API KEY ASYNCHRONOUSLY
1

Manage API keys asynchronously for non-blocking applications.

Error handling​

  • 400 Bad Request: Invalid fields or parameters.
    • Tip: Double-check required fields, corpus IDs, and role values.
  • 403 Forbidden: Insufficient permissions.
    • Tip: Only admin-level API keys can manage other API keys.
  • 404 Not Found: Invalid key ID or key already deleted.
  • 409 Conflict: Attempting to create a key with a duplicate name (if enforced by organizational policy).
  • Handle with try/except: Always wrap API key operations in try/except blocks, especially when enabling/disabling or deleting keys.

Security Tips:

  • Use the principle of least privilege: grant only the roles and corpora needed.
  • Rotate API keys regularly and immediately after staff changes.
  • Never log or share API key values in plaintext or source control.
  • Disable (do not delete) keys for temporary suspension—retain for audits.
  • Audit API key usage regularly via listing endpoints.