Authentication

Secure your Qdrant instance with API keys, JWT tokens, and TLS client certificates

Qdrant provides multiple authentication mechanisms to secure your vector database. By default, Qdrant runs without authentication, which is suitable for development but should never be used in production.

Never run Qdrant without authentication in production. An unsecured instance is open to all network interfaces and can be accessed by anyone.

API Key Authentication

API key authentication is the simplest way to secure your Qdrant instance. You can configure two types of API keys:

• Read-Write Key - Full access to all operations
• Read-Only Key - Restricted to read operations (searches, retrievals)

Setting Up API Keys

API keys are configured in the config/config.yaml file:

service:
  # Read-write API key
  api_key: your_secret_api_key_here
  
  # Read-only API key (optional)
  read_only_api_key: your_secret_read_only_api_key_here

After updating the configuration, restart Qdrant for the changes to take effect.

You can also set API keys via environment variables:

• QDRANT__SERVICE__API_KEY
• QDRANT__SERVICE__READ_ONLY_API_KEY

Using API Keys in Requests

Once configured, all API requests must include an API key. There are two ways to provide the key:

Method 1: Using the api-key Header (Recommended)

curl -X GET 'http://localhost:6333/collections' \
  -H 'api-key: your_secret_api_key_here'

Method 2: Using the Authorization Header

curl -X GET 'http://localhost:6333/collections' \
  -H 'Authorization: Bearer your_secret_api_key_here'

The api-key header is Qdrant-specific, while the Authorization: Bearer header follows standard OAuth conventions. Both methods are functionally equivalent.

Using API Keys with Client Libraries

Python

from qdrant_client import QdrantClient

client = QdrantClient(
    url="http://localhost:6333",
    api_key="your_secret_api_key_here"
)

Read-Write vs Read-Only Keys

Qdrant supports two types of API keys with different permission levels:

Read-Write Key

The read-write key (api_key) grants full access to:

• Create, update, and delete collections
• Insert, update, and delete points
• Perform searches and retrievals
• Create and delete snapshots
• Modify cluster configuration
• All administrative operations

Use case: Backend services, administrative tools, data ingestion pipelines

Read-Only Key

The read-only key (read_only_api_key) is restricted to:

• List collections and view collection info
• Retrieve points by ID
• Perform vector searches
• Scroll through points
• View cluster information (read-only)

Operations NOT allowed with read-only key:

• Creating or deleting collections
• Inserting, updating, or deleting points
• Creating indexes
• Creating snapshots
• Modifying cluster configuration

Use case: Frontend applications, public APIs, analytics dashboards, read-only clients

Use read-only keys for client-facing applications to prevent accidental or malicious data modifications.

JWT-Based Access Control (RBAC)

For fine-grained access control, Qdrant supports JWT (JSON Web Token) based authentication with Role-Based Access Control (RBAC).

Enabling JWT RBAC

Enable JWT RBAC in your configuration:

service:
  api_key: your_secret_jwt_signing_key
  jwt_rbac: true

When JWT RBAC is enabled:

• The api_key is used as the JWT signing secret
• You can generate JWT tokens with custom access rules
• Tokens can include collection-level and operation-level permissions

JWT Token Structure

JWT tokens must include an access claim defining the allowed operations:

{
  "sub": "[e-mail]",
  "exp": 1735689600,
  "access": {
    "collections": {
      "my_collection": ["read", "write"]
    }
  }
}

JWT RBAC is an advanced feature. For most use cases, simple API key authentication is sufficient.

TLS Client Certificates

For the highest level of security, Qdrant supports mutual TLS (mTLS) authentication using client certificates.

Enabling TLS

Configure TLS in your config/config.yaml:

service:
  # Enable HTTPS for REST and gRPC
  enable_tls: true
  
  # Verify client certificates (for mTLS)
  verify_https_client_certificate: false

tls:
  # Server certificate chain
  cert: ./tls/cert.pem
  
  # Server private key
  key: ./tls/key.pem
  
  # Certificate Authority certificate
  # Required for client certificate verification
  ca_cert: ./tls/cacert.pem
  
  # Certificate TTL in seconds (for rotation)
  cert_ttl: 3600

Mutual TLS (Client Certificates)

To require client certificates for authentication:

1. Set verify_https_client_certificate: true
2. Provide a CA certificate in tls.ca_cert
3. Ensure clients present valid certificates signed by the CA

Client configuration example:

Python

from qdrant_client import QdrantClient

client = QdrantClient(
    url="https://localhost:6333",
    https=True,
    verify=True,
    cert="./client-cert.pem",
    key="./client-key.pem"
)

When using TLS, ensure your certificates are properly secured and rotated regularly. The cert_ttl setting enables automatic certificate reloading for HTTPS endpoints.

Best Practices

API Key Security

Use strong, random API keys

Generate API keys using a cryptographically secure random generator:

# Generate a random 32-byte API key
openssl rand -base64 32

Never use simple or predictable values.

Always use TLS with API keys

API keys are sent with every request. Without TLS, they can be intercepted:

service:
  enable_tls: true
  api_key: your_secret_api_key_here

The configuration file warns: “If you enable this you should also enable TLS.”

Rotate API keys regularly

Qdrant supports an alternative API key (alt_api_key) to enable zero-downtime key rotation:

1. Add alt_api_key with a new key
2. Update clients to use the new key
3. Remove the old api_key and promote alt_api_key to api_key

Use read-only keys for untrusted clients

Never expose read-write keys to frontend applications or public APIs:

# Frontend client - read-only
frontend_client = QdrantClient(
    url="https://api.example.com",
    api_key="read_only_key_here"
)

# Backend service - read-write
backend_client = QdrantClient(
    url="https://api.example.com",
    api_key="read_write_key_here"
)

Store keys securely

Never commit API keys to version control. Use environment variables or secret management:

import os

client = QdrantClient(
    url=os.getenv("QDRANT_URL"),
    api_key=os.getenv("QDRANT_API_KEY")
)

Network Security

• Firewall rules: Restrict access to Qdrant ports (6333, 6334) using firewall rules
• Private networks: Deploy Qdrant in a private network, not exposed to the public internet
• Reverse proxy: Use a reverse proxy (nginx, Traefik) for additional security layers
• Rate limiting: Implement rate limiting at the proxy or application level

Monitoring Authentication

Qdrant provides audit logging for access-checked API requests:

audit:
  enabled: true
  dir: ./storage/audit
  rotation: daily
  max_log_files: 7

Audit logs include:

• Authentication method used (API key, JWT, client certificate)
• User/subject information
• Request details and outcomes
• Timestamp and client IP

Next: REST API Reference

Explore the complete REST API documentation

Related Resources

Security Guide

Comprehensive security best practices

Configuration

Complete configuration reference

Distributed Deployment

Secure multi-node clusters

Monitoring

Track authentication events