What is the difference between a read-only and a read-write API key in Qdrant, and when would you issue each?

Qdrant supports two standard API key types. The read-write key (configured as api_key) grants full access to all operations: creating and deleting collections, inserting, updating, and deleting points, performing searches, creating snapshots, modifying cluster configuration, and all administrative operations[reference:9]. The read-only key (configured as read_only_api_key) is restricted to read operations: listing collections and viewing collection info, retrieving points by ID, performing vector searches, scrolling through points, and viewing cluster information[reference:10]. It cannot create or delete collections, insert, update, or delete points, create indexes, create snapshots, or modify cluster configuration[reference:11]. The distinction is about write capability, not about data visibility - a read-only key can query any collection it can reach.

The operational value of the read-only key is least-privilege access for query-only services. In a typical RAG pipeline, the embedding and indexing service needs a read-write key to upsert vectors, while the query service that serves user requests only needs to search. Issuing a read-only key to the query service means that a compromise of that service - through a dependency vulnerability, a leaked environment variable, or a misconfigured container - cannot destroy data or exfiltrate it by writing it somewhere else. The official documentation recommends using read-only keys for client-facing applications to prevent accidental or malicious data modifications[reference:12]. The read-only key is configured separately from the read-write key and uses the same header mechanism, so the client code does not need to change beyond the key value. A service using the read-only key can still perform every read operation it needs: search, scroll, retrieve by ID, and inspect collection metadata.

The trade-off is operational convenience against blast radius. Using a single read-write key everywhere is simpler but means any compromised service can destroy or exfiltrate data. Issuing a read-only key to query services adds a small amount of configuration complexity but dramatically reduces the impact of a compromise. The common mistake is using the read-write key for everything because it is easier, then discovering during an incident that a compromised query service had delete privileges. The second mistake is assuming the read-only key is sufficient for a data ingestion pipeline that also needs to check whether a point exists before upserting - existence checks are reads and work with the read-only key, but the upsert itself does not. The third mistake is forgetting that the read-only key still has full read access to all collections; it is not a per-collection restriction. For per-collection or per-operation scoping, you need granular access API keys (JWT RBAC), which were added in Qdrant 1.9 and provide collection-level read/write/read-write permissions. Version note: the read-only key feature requires Qdrant 1.2 or later, and the exact permission set has been stable across recent releases, but the granular JWT RBAC capability is newer and has changed across versions.

Version-dependent: read-only API key support requires Qdrant 1.2 or later. The permission set described here (no writes, no collection management) has been consistent, but the exact error behavior when a read-only key attempts a write may vary. For per-collection scoping, granular access API keys were added in 1.9 and have evolved since; they use JWT tokens and can encode collection-level permissions, which is a different mechanism from the static read-only key.