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

# Azure Cosmos DB

> Client-mode REST API connector for the Azure Cosmos DB for NoSQL data plane: create and upsert and read and replace documents and SQL queries with Entra ID tokens

Technical Preview

## Overview

Client-mode REST API connector for the Azure Cosmos DB for NoSQL data plane: create and upsert and read and replace documents and SQL queries with Entra ID tokens. `BASE_ADDRESS` defaults to `https://YOUR_ACCOUNT.documents.azure.com`. Topics use `data/azure-cosmos-db/<object>/<verb>`.

| Event | Request | Source topic |
| - | - | - |
| `DocumentCreate` | `POST /dbs/{value.json.db}/colls/{value.json.coll}/docs` | `data/azure-cosmos-db/documents/create` |
| `DocumentUpsert` | `POST /dbs/{value.json.db}/colls/{value.json.coll}/docs` | `data/azure-cosmos-db/documents/upsert` |
| `DocumentGet` | `GET /dbs/{value.json.db}/colls/{value.json.coll}/docs/{value.json.id}` | `data/azure-cosmos-db/documents/get` |
| `DocumentReplace` | `PUT /dbs/{value.json.db}/colls/{value.json.coll}/docs/{value.json.id}` | `data/azure-cosmos-db/documents/replace` |
| `DocumentQuery` | `POST /dbs/{value.json.db}/colls/{value.json.coll}/docs` | `data/azure-cosmos-db/documents/query` |
| `DocumentsList` | `GET /dbs/{value.json.db}/colls/{value.json.coll}/docs` | `data/azure-cosmos-db/documents/list` |

## Authentication

Microsoft Entra ID (Cosmos DB RBAC): Authorization: \{value.json.authorization} = URL-encoded "type=aad\&ver=1.0\&sig=\<Entra access token>" (scope [https://YOUR\_ACCOUNT.documents.azure.com/.default](https://YOUR_ACCOUNT.documents.azure.com/.default); role Cosmos DB Built-in Data Contributor). A resource token (type=resource) also works. Master-key auth needs a per-request HMAC over verb, resource and date, which the REST\_API connector cannot compute, so it is not supported. x-ms-date (RFC 1123, UTC, within 15 minutes) is passed per payload.

> [!WARNING]
>
> Keep credentials in broker secrets and never retain topics that carry tokens or client secrets.

## Notes

* partition\_key is a JSON array string, e.g. \["line-1"].
* Entra RBAC covers data-plane operations only; databases and containers are created through ARM / portal.
* DocumentQuery sends \{value.json.body} = \{"query":"SELECT ...","parameters":\[...]} as application/query+json.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE AzureCosmosDbRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ACCOUNT.documents.azure.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT DocumentCreate
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/create"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-documentdb-partitionkey" "{value.json.partition_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT DocumentUpsert
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/upsert"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/upsert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-documentdb-partitionkey" "{value.json.partition_key}"
            ADD "x-ms-documentdb-is-upsert" "True"
        WITH BODY "{value.json.body}"
    ADD EVENT DocumentGet
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/get"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-documentdb-partitionkey" "{value.json.partition_key}"
    ADD EVENT DocumentReplace
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/replace"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/replace/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-documentdb-partitionkey" "{value.json.partition_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT DocumentQuery
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/query"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/query+json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-documentdb-isquery" "True"
            ADD "x-ms-documentdb-query-enablecrosspartition" "True"
            ADD "x-ms-max-item-count" "{value.json.max_items}"
        WITH BODY "{value.json.body}"
    ADD EVENT DocumentsList
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/list"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-max-item-count" "{value.json.max_items}"
```

## Sources

* [https://learn.microsoft.com/en-us/rest/api/cosmos-db/access-control-on-cosmosdb-resources](https://learn.microsoft.com/en-us/rest/api/cosmos-db/access-control-on-cosmosdb-resources)
* [https://learn.microsoft.com/en-us/rest/api/cosmos-db/create-a-document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/create-a-document)
* [https://learn.microsoft.com/en-us/rest/api/cosmos-db/get-a-document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/get-a-document)
* [https://learn.microsoft.com/en-us/rest/api/cosmos-db/replace-a-document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/replace-a-document)
* [https://learn.microsoft.com/en-us/rest/api/cosmos-db/querying-cosmosdb-resources-using-the-rest-api](https://learn.microsoft.com/en-us/rest/api/cosmos-db/querying-cosmosdb-resources-using-the-rest-api)
* [https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-setup-rbac](https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-setup-rbac)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.