> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/qdrant/qdrant/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

## 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:

```yaml theme={null}
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.

<Tip>
  You can also set API keys via environment variables:

  * `QDRANT__SERVICE__API_KEY`
  * `QDRANT__SERVICE__READ_ONLY_API_KEY`
</Tip>

### 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)

```bash theme={null}
curl -X GET 'http://localhost:6333/collections' \
  -H 'api-key: your_secret_api_key_here'
```

#### Method 2: Using the `Authorization` Header

```bash theme={null}
curl -X GET 'http://localhost:6333/collections' \
  -H 'Authorization: Bearer your_secret_api_key_here'
```

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

### Using API Keys with Client Libraries

<CodeGroup>
  ```python Python theme={null}
  from qdrant_client import QdrantClient

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

  ```javascript JavaScript theme={null}
  import { QdrantClient } from '@qdrant/js-client-rest';

  const client = new QdrantClient({
    url: 'http://localhost:6333',
    apiKey: 'your_secret_api_key_here'
  });
  ```

  ```rust Rust theme={null}
  use qdrant_client::client::QdrantClient;

  let client = QdrantClient::from_url("http://localhost:6333")
      .with_api_key("your_secret_api_key_here")
      .build()
      .await?;
  ```

  ```go Go theme={null}
  import "github.com/qdrant/go-client/qdrant"

  client, err := qdrant.NewClient(&qdrant.Config{
      Host:   "localhost:6334",
      APIKey: "your_secret_api_key_here",
  })
  ```
</CodeGroup>

## 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

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

## 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:

```yaml theme={null}
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:

```json theme={null}
{
  "sub": "user@example.com",
  "exp": 1735689600,
  "access": {
    "collections": {
      "my_collection": ["read", "write"]
    }
  }
}
```

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

## 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`:

```yaml theme={null}
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:**

<CodeGroup>
  ```python Python theme={null}
  from qdrant_client import QdrantClient

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

  ```bash cURL theme={null}
  curl --cert ./client-cert.pem \
       --key ./client-key.pem \
       --cacert ./ca-cert.pem \
       https://localhost:6333/collections
  ```
</CodeGroup>

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

## Best Practices

### API Key Security

<AccordionGroup>
  <Accordion title="Use strong, random API keys">
    Generate API keys using a cryptographically secure random generator:

    ```bash theme={null}
    # Generate a random 32-byte API key
    openssl rand -base64 32
    ```

    Never use simple or predictable values.
  </Accordion>

  <Accordion title="Always use TLS with API keys">
    API keys are sent with every request. Without TLS, they can be intercepted:

    ```yaml theme={null}
    service:
      enable_tls: true
      api_key: your_secret_api_key_here
    ```

    The configuration file warns: "If you enable this you should also enable TLS."
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="Use read-only keys for untrusted clients">
    Never expose read-write keys to frontend applications or public APIs:

    ```python theme={null}
    # 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"
    )
    ```
  </Accordion>

  <Accordion title="Store keys securely">
    Never commit API keys to version control. Use environment variables or secret management:

    ```python theme={null}
    import os

    client = QdrantClient(
        url=os.getenv("QDRANT_URL"),
        api_key=os.getenv("QDRANT_API_KEY")
    )
    ```
  </Accordion>
</AccordionGroup>

### 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:

```yaml theme={null}
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

<Card title="Next: REST API Reference" icon="book" href="/api/rest/collections">
  Explore the complete REST API documentation
</Card>

## Related Resources

<CardGroup cols={2}>
  <Card title="Security Guide" icon="shield-halved" href="/deployment/security">
    Comprehensive security best practices
  </Card>

  <Card title="Configuration" icon="gear" href="/operations/configuration">
    Complete configuration reference
  </Card>

  <Card title="Distributed Deployment" icon="server" href="/deployment/distributed">
    Secure multi-node clusters
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/operations/monitoring">
    Track authentication events
  </Card>
</CardGroup>