Connect to Azure AI Search using key authentication

Article
04/22/2024

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.

Key-based authentication is the default. You can disable it if you opt in for role-based authentication.

Note

A quick note about key terminology. An API key is a GUID used for authentication. A separate term, document key is a unique string in your indexed content that uniquely identifies 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 ¹	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.

Admin keys are used for creating, modifying, or deleting objects. Admin keys are also used to GET object definitions and system information.

Query keys are typically distributed to client applications that issue queries.

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 LIST Indexes or GET Service Statistics.

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

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-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=2023-11-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.

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.

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.

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

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>

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>

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.

Sign in to the Azure portal and find your search service.
Under Settings, select 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=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.

Under Settings, select Keys, then 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 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.

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.

Navigate to your search service page in Azure portal.
On the left navigation 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

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.