clarified API key usage

Author: HeidiSteen

articles/search/search-security-api-keys.md

@@ -10,15 +10,17 @@ ms.service: cognitive-search
 ms.custom:
   - ignite-2023
 ms.topic: how-to
-ms.date: 02/15/2024
+ms.date: 04/22/2024
 ---
 
 # 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.
 
+Key-based authentication is the default. You can disable it if you opt in for role-based authentication.
+
 > [!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.
+> A quick note about "key" terminology. An *API key*, as 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 uniquely identifies documents in a search index.
 
 ## Types of API keys
 
@@ -35,25 +37,41 @@ Visually, there's no distinction between an admin key or query key. Both keys ar
 
 ## 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](/rest/api/searchservice/). 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](search-security-rbac.md) 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.
+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](/rest/api/searchservice/). 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](search-security-rbac.md) if you can't use hard-coded keys in your code.
 
-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](#permissions-to-view-or-manage-api-keys).
+Admin keys are used for creating, modifying, or deleting objects. Admin keys are also used to GET object definitions and system information.
 
-Best practices for using hard-coded keys in source files include:
+Query keys are typically distributed to client applications that issue queries.
 
-+ 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. 
+### [**REST API**](#tab/rest-use)
 
-+ Always check code, samples, and training material before publishing to make sure you didn't leave valid API keys behind.
+**How API keys are used in REST calls**:
 
-+ For production workloads, switch to [Microsoft Entra ID and role-based access](search-security-rbac.md). Or, if you want to continue using API keys, be sure to always monitor [who has access to your API keys](#secure-api-keys) and [regenerate API keys](#regenerate-admin-keys) on a regular cadence.
+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.
+
+```http
+### Create a new index
+POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
+  Content-Type: application/json
+  api-key: {{apiKey}}
+
+    {
+        "name": "my-new-index",  
+        "fields": [
+            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
+            {"name": "Name", "type": "Edm.String", "searchable": true }
+         ]
+   }
+```
 
-### [**Portal**](#tab/portal-use)
+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](/rest/api/searchservice/documents/search-get), [Autocomplete](/rest/api/searchservice/documents/autocomplete-get), [Suggest](/rest/api/searchservice/documents/suggest-get), or [GET Document](/rest/api/searchservice/documents/get). 
 
-**How API keys are used in the Azure portal**:
+```http
+GET /indexes/my-new-index/docs?search=*&api-version=2020-06-30&api-key={{apiKey}}
+```
 
-+ Key authentication is built in. By default, the portal tries API keys first. However, if you [disable API keys](search-security-rbac.md#disable-api-key-authentication) and set up role assignments, the portal uses role assignments instead.
+> [!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.
 
 ### [**PowerShell**](#tab/azure-ps-use)
 
@@ -70,18 +88,11 @@ $headers = @{
 
 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](search-get-started-powershell.md).
 
-### [**REST API**](#tab/rest-use)
-
-**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.
+### [**Portal**](#tab/portal-use)
 
-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]`
+**How API keys are used in the Azure portal**:
 
-> [!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.
++ Key authentication is built in. By default, the portal tries API keys first. However, if you [disable API keys](search-security-rbac.md#disable-api-key-authentication) and set up role assignments, the portal uses role assignments instead.
 
 ---
 
@@ -214,7 +225,7 @@ After you create new keys via portal or management layer, access is restored to
 
 Use role assignments to restrict access to API keys.
 
-Note that it's not possible to use [customer-managed key encryption](search-security-manage-encryption-keys.md) 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.
+It's not possible to use [customer-managed key encryption](search-security-manage-encryption-keys.md) 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.
 
@@ -224,6 +235,14 @@ Note that it's not possible to use [customer-managed key encryption](search-secu
 
 1. 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](search-security-rbac.md). Or, if you want to continue using API keys, be sure to always monitor [who has access to your API keys](#secure-api-keys) and [regenerate API keys](#regenerate-admin-keys) on a regular cadence.
+
 ## See also
 
 + [Security in Azure AI Search](search-security-overview.md)