Chroma Authentication: Methods, Credentials & Security

Authentication overview

Chroma, as a vector database, handles authentication differently based on its deployment model: either as a self-hosted open-source instance or through the managed Chroma Cloud service. For local and self-hosted open-source deployments, Chroma itself does not feature an internal authentication layer. Instead, access control is typically managed externally through network security, firewalls, and secure access to the server hosting the Chroma instance. When connecting to a self-hosted Chroma server over a network, client applications must ensure the connection is secure, often via HTTPS, and that the server is protected by appropriate access controls.

In contrast, Chroma Cloud, a managed service, implements a robust authentication mechanism to secure access to user data. This is essential for multitenant environments where multiple users' data is hosted and isolated. Chroma Cloud leverages API keys to authenticate requests, ensuring that only authorized applications can interact with specific vector collections and embeddings. This managed approach offloads the burden of security infrastructure from the developer, providing a more streamlined and secure experience for cloud-based applications.

Understanding the distinction between self-hosted and cloud authentication is critical for implementing secure integrations with Chroma. Developers should select the appropriate security measures based on their chosen deployment, ensuring data privacy and operational integrity.

Supported authentication methods

The primary authentication method for Chroma depends on whether you are using a self-hosted open-source instance or the Chroma Cloud service.

API Key Authentication (Chroma Cloud)

Chroma Cloud utilizes API keys for authenticating requests. An API key is a unique token that identifies your application and grants it permission to interact with your Chroma Cloud resources. These keys are generated and managed within the Chroma Cloud dashboard. When making requests to Chroma Cloud, the API key must be included in the request headers, typically as part of an X-Chroma-Auth-Token or similar header. This method provides a simple yet effective way to secure access to your hosted vector database.

Network-Level Security (Self-Hosted Chroma)

For self-hosted open-source Chroma instances, the database itself does not have built-in authentication. Access control is managed at the network and infrastructure layers. This typically involves:

• Firewall Rules: Restricting access to the Chroma server's port (default 8000) to only trusted IP addresses or internal networks.
• VPNs or Private Networks: Ensuring that connections to the Chroma instance occur over secure, private networks.
• Reverse Proxies: Deploying a reverse proxy (e.g., Nginx, Envoy) in front of Chroma to handle authentication (e.g., basic auth, OAuth2), SSL/TLS encryption, and rate limiting. This external layer manages client authentication before forwarding requests to the Chroma server. More information on securing APIs with reverse proxies can be found in general API security guides, such as Kong's API Security Fundamentals.
• Kubernetes or Container Orchestration: Utilizing platform-level security features and network policies when deploying Chroma in containerized environments.

Client-Side Handling (Local Chroma)

When running Chroma in-memory or on a local filesystem for development or testing, authentication is generally not a concern as the database is accessed directly by the application on the same machine. Security is implicitly managed by the host system's security practices.

Getting your credentials

The process for obtaining credentials depends entirely on your Chroma deployment choice.

Chroma Cloud API Keys

1. Sign Up/Log In: Navigate to the Chroma Cloud website and either sign up for a new account or log into your existing one.
2. Access Dashboard: Once logged in, access your Chroma Cloud dashboard.
3. Generate API Key: Look for a section related to API Keys, Security, or Access Tokens. Follow the on-screen instructions to generate a new API key. You will typically be prompted to give your key a descriptive name.
4. Copy Key: The generated API key will be displayed once. It is crucial to copy this key immediately and store it securely, as it may not be retrievable later for security reasons. Treat API keys like passwords.
5. Configure Environment: Set your API key as an environment variable (e.g., CHROMA_API_KEY) or pass it directly in your application code, adhering to security best practices. For detailed instructions, refer to the Chroma Cloud API Keys documentation.

Self-Hosted Chroma (No inherent credentials)

For self-hosted Chroma instances, there are no specific credentials generated by Chroma itself. Instead, you will manage access through your chosen infrastructure. For example:

• If using a reverse proxy with Basic Authentication, you would create and manage usernames and passwords within your proxy configuration (e.g., an .htpasswd file for Nginx).
• If integrating with an OAuth 2.0 provider through a proxy, you would configure client IDs and secrets with that provider and your proxy. The OAuth.net website provides comprehensive resources on OAuth 2.0 implementation details.
• For network-level restrictions, you would configure firewall rules using tools like iptables or your cloud provider's security groups.

Authenticated request example

This example demonstrates how to make an authenticated request to Chroma Cloud using Python. The API key is passed in the X-Chroma-Auth-Token header.

import chromadb
import os

# Retrieve your Chroma Cloud host and API key from environment variables
CHROMA_HOST = os.getenv("CHROMA_HOST") # e.g., 'https://your-instance.aws-region.chromadb.cloud'
CHROMA_API_KEY = os.getenv("CHROMA_API_KEY")

if not CHROMA_HOST or not CHROMA_API_KEY:
    raise ValueError("CHROMA_HOST and CHROMA_API_KEY environment variables must be set.")

# Initialize the Chroma client for Chroma Cloud
client = chromadb.HttpClient(
    host=CHROMA_HOST,
    headers={
        "X-Chroma-Auth-Token": CHROMA_API_KEY
    }
)

try:
    # Example: List all collections
    collections = client.list_collections()
    print("Successfully listed collections:")
    for col in collections:
        print(f"- {col.name}")

    # Example: Get a specific collection (replace 'my_collection' with an actual collection name)
    # collection = client.get_or_create_collection(name="my_collection")
    # print(f"Accessed collection: {collection.name}")

except Exception as e:
    print(f"An error occurred during authentication or request: {e}")
    print("Please ensure your CHROMA_HOST and CHROMA_API_KEY are correct and have appropriate permissions.")

For self-hosted instances, the client initialization would differ, typically connecting directly to the local or network IP address without explicit headers for authentication within the Chroma client itself, relying instead on external security measures.

import chromadb

# For a local, in-memory client (no host, no auth)
# client = chromadb.Client()

# For a self-hosted client running on localhost:8000 (no auth within Chroma client)
client = chromadb.HttpClient(host="http://localhost:8000")

try:
    collections = client.list_collections()
    print("Successfully listed collections from self-hosted instance:")
    for col in collections:
        print(f"- {col.name}")
except Exception as e:
    print(f"An error occurred: {e}")

Security best practices

Implementing strong security practices is crucial for protecting your Chroma data, regardless of the deployment model.

For Chroma Cloud Users

• API Key Management: Treat your API keys as sensitive credentials. Never hardcode them directly into your application code. Use environment variables, a secrets manager, or a secure configuration management system.
• Key Rotation: Regularly rotate your API keys. If a key is compromised, revoking it and issuing a new one minimizes the potential damage. The Chroma Cloud documentation on API keys provides guidance on rotation.
• Least Privilege: If Chroma Cloud supports granular permissions for API keys (check their latest documentation), configure keys with the minimum necessary permissions required for your application to function.
• HTTPS/TLS: All communication with Chroma Cloud is automatically secured via HTTPS/TLS, ensuring data in transit is encrypted. Verify that your client library is configured to use HTTPS.
• Monitor Usage: Regularly monitor the usage of your API keys for any unusual activity that might indicate compromise.

For Self-Hosted Chroma Users

• Network Isolation: Deploy your Chroma instance behind a firewall and restrict access to specific IP ranges or internal networks. Avoid exposing the Chroma port directly to the public internet without an intervening secure proxy.
• Reverse Proxy with Authentication: Strongly consider deploying a reverse proxy (e.g., Nginx, Caddy, Envoy, API Gateway like Kong) in front of your Chroma instance. This proxy can enforce authentication (e.g., OAuth 2.0, Basic Auth, mTLS), SSL/TLS termination, and request logging. For instance, Cloudflare Tunnel documentation provides examples of securing internal services.
• HTTPS/TLS Encryption: Configure your reverse proxy to enforce HTTPS for all client-to-proxy communication and, if necessary, between the proxy and the Chroma instance (though often not needed if both are on a secure internal network). Use valid SSL certificates.
• Access Logging and Monitoring: Implement comprehensive access logging on your proxy and server infrastructure to track who is accessing Chroma and when. Integrate these logs with a security information and event management (SIEM) system.
• Regular Updates: Keep your Chroma instance, operating system, and any proxy software updated to the latest security patches to mitigate known vulnerabilities.
• Container Security: If deploying with Docker or Kubernetes, follow container security best practices, including using minimal base images, scanning for vulnerabilities, and applying Kubernetes network policies.
• Data Encryption at Rest: While Chroma itself might not encrypt data at rest internally by default, ensure the underlying filesystem or storage solution where Chroma stores its data is encrypted.