Work with account keys and connection strings for an Azure Cosmos account using Azure CLI

APPLIES TO: SQL API Cassandra API Gremlin API Table API Azure Cosmos DB API for MongoDB

Prerequisites

  • Use the Bash environment in Azure Cloud Shell.

    Launch Cloud Shell in a new window

  • If you prefer, install the Azure CLI to run CLI reference commands.

    • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For additional sign-in options, see Sign in with the Azure CLI.

    • When you're prompted, install Azure CLI extensions on first use. For more information about extensions, see Use extensions with the Azure CLI.

    • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

  • This article requires version 2.9.1 or later of the Azure CLI. If using Azure Cloud Shell, the latest version is already installed.

Sample script

This script demonstrates four operations.

  • List all account keys
  • List read only account keys
  • List connection strings
  • Regenerate account keys

Note

This sample demonstrates using a SQL (Core) API account but the account key and connection string operations are identical across all database APIs in Cosmos DB.

#!/bin/bash
# Reference: az cosmosdb | https://docs.microsoft.com/cli/azure/cosmosdb
# --------------------------------------------------
#
# Account key operations for an Azure Cosmos account
#
#

# Account key operations:
#   List all account keys
#   List read only account keys
#   List connection strings
#   Regenerate account keys

# Resource group and Cosmos account variables
uniqueId=$RANDOM
resourceGroupName="Group-$uniqueId"
location='westus2'
accountName="cosmos-$uniqueId" #needs to be lower case

# Create a resource group
az group create -n $resourceGroupName -l $location

# Create a Cosmos DB account with default values
# Use appropriate values for --kind or --capabilities for other APIs
az cosmosdb create -n $accountName -g $resourceGroupName

read -p "Press any key to list account keys"
# List all account keys
az cosmosdb keys list \
    -n $accountName \
    -g $resourceGroupName

read -p "Press any key to list read only account keys"
# List read-only keys
az cosmosdb keys list \
    -n $accountName \
    -g $resourceGroupName \
    --type read-only-keys

read -p "Press any key to list connection strings"
# List connection strings
az cosmosdb keys list \
    -n $accountName \
    -g $resourceGroupName \
    --type connection-strings

read -p "Press any key to regenerate secondary account keys"
# Regenerate secondary account keys
# key-kind values: primary, primaryReadonly, secondary, secondaryReadonly
az cosmosdb keys regenerate \
    -n $accountName \
    -g $resourceGroupName \
    --key-kind secondary
    

Clean up deployment

After the script sample has been run, the following command can be used to remove the resource group and all resources associated with it.

az group delete --name $resourceGroupName

Script explanation

This script uses the following commands. Each command in the table links to command specific documentation.

Command Notes
az group create Creates a resource group in which all resources are stored.
az cosmosdb create Creates an Azure Cosmos DB account.
az cosmosdb keys list List the keys for an Azure Cosmos DB account.
az cosmosdb list-read-only-keys List the read only keys for an Azure Cosmos DB account.
az cosmosdb list-connection-strings List the connection strings for an Azure Cosmos DB account.
az cosmosdb regenerate-key Regenerate keys for an Azure Cosmos DB account.
az group delete Deletes a resource group including all nested resources.

Next steps

For more information on the Azure Cosmos DB CLI, see Azure Cosmos DB CLI documentation.

All Azure Cosmos DB CLI script samples can be found in the Azure Cosmos DB CLI GitHub Repository.