Connect to Azure AI Search using keys

Azure AI Search supports both identity-based and key-based authentication (default) for connections to your search service.

A request made to a search service endpoint is accepted if both the request and the API key are valid and if the search service is configured to allow API keys on a request.

Important

When you create a search service, key-based authentication is the default, but it's not the most secure option. We recommend that you replace it with role-based access.

Prerequisites

You must be an Owner, Contributor, or Search Service Contributor to view or manage keys.

Enabled by default

In the Azure portal, authentication is specified on the Settings > Keys page. Options set to either API keys (default) or Both allow API keys on a request.

Types of keys

An API key is a unique string composed of 52 randomly generated numbers and letters. Visually, there's no distinction between an admin key or query key. If you lose track of what type of key is specified in your application, you can check the key values in the Azure portal.

There are two kinds of keys used for authenticating a request:

Type	Permission level	How it's created	Maximum
Admin	Full access (read-write) for all data plane (content) operations	Two admin keys, primary and secondary, are generated when the service is created and can be individually regenerated on demand. Having two allows you to roll over one key while using the second key for continued access to the service.	2
Query	Read-only access, scoped to the documents collection of a search index	One query key is generated with the service. More can be created on demand by a search service administrator.	50

Find existing keys

You can view and manage API keys using the Azure portal, PowerShell, Azure CLI, or REST API.

Sign in to the Azure portal and find your search service.
From the left pane, select Settings > Keys to view admin and query keys.

Run the following commands to return admin and query API keys, respectively. For help with REST, see Manage your Azure AI Search service with REST APIs.

Return admin keys:

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2025-05-01

Return query keys:

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2025-05-01

Reference: Admin Keys - Get, Query Keys - List By Search Service

Use the Azure SDK for Python to retrieve API keys programmatically. Install the management SDK:

pip install azure-mgmt-search azure-identity

Run the following code to return admin and query API keys:

import os
from azure.identity import DefaultAzureCredential
from azure.mgmt.search import SearchManagementClient

# Set up variables
subscription_id = os.environ["AZURE_SUBSCRIPTION_ID"]
resource_group = "your-resource-group"
search_service_name = "your-search-service"

# Create the management client
credential = DefaultAzureCredential()
client = SearchManagementClient(credential, subscription_id)

# Get admin keys
admin_keys = client.admin_keys.get(resource_group, search_service_name)
print(f"Primary admin key: {admin_keys.primary_key}")
print(f"Secondary admin key: {admin_keys.secondary_key}")

# Get query keys
query_keys = client.query_keys.list_by_search_service(resource_group, search_service_name)
for key in query_keys:
    print(f"Query key '{key.name}': {key.key}")

Reference: SearchManagementClient | AdminKeys | QueryKeys

Run the following commands to return admin and query API keys, respectively. For help with PowerShell, see Manage your Azure AI Search service using PowerShell.

Install the Az.Search module:
```
Install-Module Az.Search
```

Return admin keys:

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Return query keys:

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Run the following commands to return admin and query API keys, respectively. For help with the Azure CLI, see Manage your Azure AI Search service using the Azure CLI.

Return admin keys:

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

Return query keys:

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

Use keys on connections

Key-based authentication is used only for data plane (content) requests, such as creating or querying index and any other action that's performed using the Search Service REST API.

In your source code, you can directly specify the API key in a request header. Alternatively, you can store it as an environment variable or app setting in your project and then reference the variable in the request.

Admin keys are used for creating, modifying, or deleting objects.
Admin keys are also used to GET object definitions and system information, such as LIST Indexes or GET Service Statistics.
Query keys are typically distributed to client applications that issue queries.

Recall that key authentication is enabled by default and supports data plane operations such as indexing and queries.

However, if you disable API keys and set up role assignments, the Azure portal uses role assignments instead.

Set an admin key in the request header. You can't pass admin keys on the URI or in the body of the request.

Here's an example of admin API key usage on a create index request:

@baseUrl=https://my-demo-search-service.search.windows.net
@adminApiKey=aaaabbbb-0000-cccc-1111-dddd2222eeee

### Create an index
POST {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

Set a query key in a request header for POST, or on the URI for GET. Query keys are used for operations that target the index/docs collection: Search Documents, Autocomplete, Suggest, or GET Document.

Here's an example of query API key usage on a Search Documents (GET) request:

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2025-09-01&api-key={{queryApiKey}}

Note

It's considered a poor security practice to pass sensitive data such as an api-key in the request URI. For this reason, Azure AI Search only accepts a query key as an api-key in the query string. As a general rule, we recommend passing your api-key as a request header.

It's a best practice to set the API key as an environment variable, but for simplicity, this example shows it as a string. The example uses a query API key for a query operation.

# Import libraries
from azure.search.documents import SearchClient
from azure.core.credentials import AzureKeyCredential
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Variables for endpoint, keys, index
search_endpoint: str = "https://<Put your search service NAME here>.search.windows.net/"
credential = AzureKeyCredential("Your search service query key")
index_name: str = "hotels-quickstart-python"

# Set up the client
search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

# Run the query
results =  search_client.search(query_type='simple',
    search_text="*" ,
    select='HotelName,Description,Tags',
    include_total_count=True)

print ('Total Documents Matching Query:', results.get_count())
for result in results:
    print(result["@search.score"])
    print(result["HotelName"])
    print(result["Tags"])
    print(f"Description: {result['Description']}")

Set API keys in the request header using the following syntax:

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Use a variable to contain the fully qualified query:

$url = '<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs?api-version=2025-09-01&search=attached restaurant&searchFields=Description,Tags&$select=HotelId,HotelName,Tags,Description&$count=true'

Send the request to the search service:

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

More script examples for other operations can be found at Quickstart: Create an Azure AI Search index in PowerShell using REST APIs.

Create query keys

Query keys are used for read-only access to documents within an index for operations targeting a documents collection. Search, filter, and suggestion queries are all operations that take a query key. Any read-only operation that returns system data or object definitions, such as an index definition or indexer status, requires an admin key.

Restricting access and operations in client apps is essential to safeguarding the search assets on your service. Always use a query key rather than an admin key for any query originating from a client app.

Sign in to the Azure portal and find your search service.
From the left pane, select Settings > Keys to view API keys.
Under Manage query keys, use the query key already generated for your service, or create new query keys. The default query key isn't named, but other generated query keys can be named for manageability.

Use Create Query Keys in the Management REST API.

You must have a valid role assignment to create or manage API keys. See Manage your Azure AI Search service with REST APIs for guidance on meeting role requirements using the REST APIs.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2025-05-01

Regenerate admin keys

Two admin keys are created for each service so that you can rotate a primary key while using the secondary key for business continuity.

Sign in to the Azure portal and find your search service.
From the left pane, select Settings > Keys.
Copy the secondary key.
For all applications, update the API key settings to use the secondary key.
Regenerate the primary key.
Update all applications to use the new primary key.

If you inadvertently regenerate both keys at the same time, all client requests using those keys will fail with HTTP 403 Forbidden. However, content isn't deleted and you aren't locked out permanently.

You can still access the service through the Azure portal or programmatically. Management functions are operative through a subscription ID not a service API key, and are thus still available even if your API keys aren't.

After you create new keys via portal or management layer, access is restored to your content (indexes, indexers, data sources, synonym maps) once you provide those keys on requests.

Migrate from keys to roles

If you want to transition to role-based access, it's helpful to understand how keys map to built-in roles in Azure AI Search:

An admin key corresponds to the Search Service Contributor and Search Index Data Contributor roles.
A query key corresponds to the Search Index Data Reader role.

Secure keys

Use role assignments to restrict access to API keys.

It's not possible to use customer-managed key encryption to encrypt API keys. Only sensitive data within the search service itself (for example, index content or connection strings in data source object definitions) can be CMK-encrypted.

Sign in to the Azure portal and find your search service.
From the left pane, select Access control (IAM), and then select the Role assignments tab.
In the Role filter, select the roles that have permission to view or manage keys (Owner, Contributor, Search Service Contributor). The resulting security principals assigned to those roles have key permissions on your search service.
As a precaution, also check the Classic administrators tab to determine whether administrators and co-administrators have access.

Best practices

For production workloads, switch to Microsoft Entra ID and role-based access. Alternatively, if you want to continue using API keys, be sure to always monitor who has access to your API keys and regenerate API keys on a regular cadence.
Only use API keys if data disclosure isn't a risk (for example, when using sample data) and if you're operating behind a firewall. Exposing API keys puts both your data and your search service at risk of unauthorized use.
If you use an API key, store it securely somewhere else, such as in Azure Key Vault. Don't include the API key directly in your code, and never post it publicly.
Always check code, samples, and training material before publishing to make sure you don't inadvertently expose an API key.

คำติชม

หน้านี้มีประโยชน์หรือไม่

Last updated on 2026-01-20

แชร์ผ่าน

Connect to Azure AI Search using keys

Prerequisites

Enabled by default

Types of keys

Find existing keys

Use keys on connections

Create query keys

Regenerate admin keys

Migrate from keys to roles

Secure keys

Best practices

Related content

คำติชม

แหล่งทรัพยากรเพิ่มเติม