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 will be accepted if both the request and the API key are valid.
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.|
1 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:
During early development and proof-of-concept testing when security is looser, use sample or public data.
For mature solutions or production scenarios, switch to Microsoft Entra ID and role-based access to eliminate the need for having hard-coded keys. 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.
Key authentication is built in so no action is required. By default, the portal uses API keys to authenticate the request automatically. However, if you disable API keys and set up role assignments, the portal uses role assignments instead.
In Azure AI Search, most tasks can be performed in Azure portal, including object creation, indexing through the Import data wizard, and queries through Search explorer.
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:
- Search Service Contributor
- Administrator and co-administrator (classic)
The following roles don't have access to API keys:
- Search Index Data Contributor
- Search Index Data Reader
Find existing keys
Under Settings, select Keys to view admin and query keys.
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.
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.
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.
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.
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.