Connect to Azure AI Search using key authentication

Azure AI Search offers key-based authentication that you can use on connections to your search service. An API key is a unique string composed of 52 randomly generated numbers and letters. A request made to a search service endpoint is accepted if both the request and the API key are valid.

Note

A quick note about how "key" terminology is used in Azure AI Search. An "API key", which is described in this article, refers to a GUID used for authenticating a request. A separate term, "document key", refers to a unique string in your indexed content that's used to uniquely identify documents in a search index.

Types of API keys

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

Type	Permission level	Maximum	How created
Admin	Full access (read-write) for all content operations	2 1	Two admin keys, referred to as primary and secondary keys in the portal, are generated when the service is created and can be individually regenerated on demand.
Query	Read-only access, scoped to the documents collection of a search index	50	One query key is generated with the service. More can be created on demand by a search service administrator.

¹ Having two allows you to roll over one key while using the second key for continued access to the service.

Visually, there's no distinction between an admin key or query key. Both keys are strings composed of 52 randomly generated alpha-numeric characters. If you lose track of what type of key is specified in your application, you can check the key values in the portal.

Use API keys on connections

API keys are used for data plane (content) requests, such as creating or accessing an index or any other request that's represented in the Search REST APIs. Upon service creation, an API key is the only authentication mechanism for data plane operations, but you can replace or supplement key authentication with Azure roles if you can't use hard-coded keys in your code.

API keys are specified on client requests to a search service. Passing a valid API key on the request is considered proof that the request is from an authorized client. If you're creating, modifying, or deleting objects, you'll need an admin API key. Otherwise, query keys are typically distributed to client applications that issue queries.

You can specify API keys in a request header for REST API calls, or in code that calls the azure.search.documents client libraries in the Azure SDKs. If you're using the Azure portal to perform tasks, your role assignment determines the level of access.

Best practices for using hard-coded keys in source files include:

• 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. Exposure of API keys is a risk to both data and to unauthorized use of your search service.

• Always check code, samples, and training material before publishing to make sure you didn't leave valid API keys behind.

• For production workloads, switch to Microsoft Entra ID and role-based access. Or, 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.

Portal

How API keys are used in the Azure portal:

• Key authentication is built in. By default, the portal tries API keys first. However, if you disable API keys and set up role assignments, the portal uses role assignments instead.

PowerShell

How API keys are used in PowerShell:

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' }

A script example showing API key usage for various operations can be found at Quickstart: Create an Azure AI Search index in PowerShell using REST APIs.

REST API

How API keys are used in REST calls:

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

Admin keys are used for create-read-update-delete operation and on requests issued to the search service itself, such as listing objects or requesting service statistics.

Query keys are used for search, suggestion, or lookup operations that target the index/docs collection. For POST, set api-key in the request header. Or, put the key on the URI for a GET: GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]

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.

Permissions to view or manage API keys

Permissions for viewing and managing API keys are conveyed through role assignments. Members of the following roles can view and regenerate keys:

• Owner
• Contributor
• Search Service Contributor
• Administrator and co-administrator (classic)

The following roles don't have access to API keys:

• Reader
• Search Index Data Contributor
• Search Index Data Reader

Find existing keys

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

Portal

1. Sign in to the Azure portal and find your search service.

2. Under Settings, select Keys to view admin and query keys.

PowerShell

1. Install the Az.Search module:

   Install-Module Az.Search
   

2. Return admin keys:

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

3. Return query keys:

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

Azure CLI

Use the following commands to return admin and query API keys, respectively:

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

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

REST API

Use List Admin Keys or List Query Keys in the Management REST API to return API keys.

You must have a valid role assignment to return or update 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/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

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.

Portal

1. Sign in to the Azure portal and find your search service.

2. Under Settings, select Keys to view API keys.

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

   

PowerShell

A script example showing API key usage can be found at Create or delete query keys.

Azure CLI

A script example showing query key usage can be found at Create or delete query keys.

REST API

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=2023-11-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.

1. Under Settings, select Keys, then copy the secondary key.

2. For all applications, update the API key settings to use the secondary key.

3. Regenerate the primary key.

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

Secure API keys

Use role assignments to restrict access to API keys.

Note that 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.

1. Navigate to your search service page in Azure portal.

2. On the left navigation pane, select Access control (IAM), and then select the Role assignments tab.

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

4. As a precaution, also check the Classic administrators tab to determine whether administrators and co-administrators have access.

See also

• Security in Azure AI Search
• Azure role-based access control in Azure AI Search
• Manage using PowerShell