0
# Authentication Key Management
1

2
Management of admin and query keys for search service authentication. Admin keys provide full access to the search service for index management and data operations, while query keys provide read-only access specifically for search and lookup operations.
3

4
## Capabilities
5

6
### Admin Key Operations
7

8
Admin keys provide full administrative access to the search service, enabling index creation, data upload, and service configuration. Each service has two admin keys (primary and secondary) for key rotation scenarios.
9

10
```python { .api }
11
def get(
12
    resource_group_name: str,
13
    search_service_name: str,
14
    *,
15
    client_request_id: Optional[str] = None,
16
    **kwargs
17
) -> AdminKeyResult:
18
    """
19
    Get the admin API keys for a search service.
20
    
21
    Parameters:
22
        resource_group_name (str): Resource group name
23
        search_service_name (str): Search service name
24
        client_request_id (str, optional): Client-generated request ID
25
        
26
    Returns:
27
        AdminKeyResult: Container with primary and secondary admin keys
28
        
29
    Raises:
30
        ResourceNotFoundError: Service does not exist
31
        HttpResponseError: Access denied or service error
32
    """
33

34
def regenerate(
35
    resource_group_name: str,
36
    search_service_name: str,
37
    key_kind: AdminKeyKind,
38
    *,
39
    client_request_id: Optional[str] = None,
40
    **kwargs
41
) -> AdminKeyResult:
42
    """
43
    Regenerate either the primary or secondary admin key.
44
    
45
    Parameters:
46
        resource_group_name (str): Resource group name
47
        search_service_name (str): Search service name
48
        key_kind (AdminKeyKind): Which key to regenerate (primary or secondary)
49
        client_request_id (str, optional): Client-generated request ID
50
        
51
    Returns:
52
        AdminKeyResult: Updated admin keys with new regenerated key
53
        
54
    Raises:
55
        ResourceNotFoundError: Service does not exist
56
        HttpResponseError: Access denied or invalid key kind
57
    """
58
```
59

60
**Usage Example:**
61

62
```python
63
from azure.mgmt.search.models import AdminKeyKind
64

65
# Get current admin keys
66
admin_keys = client.admin_keys.get("my-resource-group", "my-search-service")
67
print(f"Primary Key: {admin_keys.primary_key}")
68
print(f"Secondary Key: {admin_keys.secondary_key}")
69

70
# Regenerate the primary admin key (for key rotation)
71
new_keys = client.admin_keys.regenerate(
72
    resource_group_name="my-resource-group",
73
    search_service_name="my-search-service",
74
    key_kind=AdminKeyKind.PRIMARY
75
)
76
print(f"New Primary Key: {new_keys.primary_key}")
77
print(f"Secondary Key (unchanged): {new_keys.secondary_key}")
78

79
# Best practice: Use secondary key in applications, then regenerate primary,
80
# update applications to use new primary, then regenerate secondary
81
```
82

83
### Query Key Operations
84

85
Query keys provide read-only access for search operations. Unlike admin keys, you can create multiple query keys and delete individual keys as needed for different applications or users.
86

87
```python { .api }
88
def create(
89
    resource_group_name: str,
90
    search_service_name: str,
91
    name: str,
92
    *,
93
    client_request_id: Optional[str] = None,
94
    **kwargs
95
) -> QueryKey:
96
    """
97
    Create a new query API key.
98
    
99
    Parameters:
100
        resource_group_name (str): Resource group name
101
        search_service_name (str): Search service name
102
        name (str): Descriptive name for the query key
103
        client_request_id (str, optional): Client-generated request ID
104
        
105
    Returns:
106
        QueryKey: The new query key with name and key value
107
        
108
    Raises:
109
        ResourceNotFoundError: Service does not exist
110
        HttpResponseError: Access denied or quota exceeded
111
    """
112

113
def list_by_search_service(
114
    resource_group_name: str,
115
    search_service_name: str,
116
    *,
117
    client_request_id: Optional[str] = None,
118
    **kwargs
119
) -> ItemPaged[QueryKey]:
120
    """
121
    List all query keys for a search service.
122
    
123
    Parameters:
124
        resource_group_name (str): Resource group name
125
        search_service_name (str): Search service name
126
        client_request_id (str, optional): Client-generated request ID
127
        
128
    Returns:
129
        ItemPaged[QueryKey]: Paginated list of query keys
130
        
131
    Raises:
132
        ResourceNotFoundError: Service does not exist
133
    """
134

135
def delete(
136
    resource_group_name: str,
137
    search_service_name: str,
138
    key: str,
139
    *,
140
    client_request_id: Optional[str] = None,
141
    **kwargs
142
) -> None:
143
    """
144
    Delete a query key by its key value.
145
    
146
    Parameters:
147
        resource_group_name (str): Resource group name
148
        search_service_name (str): Search service name
149
        key (str): The query key value to delete
150
        client_request_id (str, optional): Client-generated request ID
151
        
152
    Raises:
153
        ResourceNotFoundError: Service or key does not exist
154
    """
155
```
156

157
**Usage Example:**
158

159
```python
160
# Create query keys for different applications
161
web_app_key = client.query_keys.create(
162
    resource_group_name="my-resource-group",
163
    search_service_name="my-search-service",
164
    name="web-application"
165
)
166
print(f"Web App Key: {web_app_key.key}")
167

168
mobile_app_key = client.query_keys.create(
169
    resource_group_name="my-resource-group",
170
    search_service_name="my-search-service",
171
    name="mobile-application"
172
)
173
print(f"Mobile App Key: {mobile_app_key.key}")
174

175
# List all query keys
176
query_keys = client.query_keys.list_by_search_service(
177
    "my-resource-group", 
178
    "my-search-service"
179
)
180
for key in query_keys:
181
    print(f"Query Key: {key.name} - {key.key}")
182

183
# Delete a specific query key
184
client.query_keys.delete(
185
    resource_group_name="my-resource-group",
186
    search_service_name="my-search-service",
187
    key=mobile_app_key.key
188
)
189
print("Mobile app key deleted")
190
```
191

192
## Data Models
193

194
### AdminKeyResult
195

196
Container for the two admin API keys that provide full service access.
197

198
```python { .api }
199
class AdminKeyResult:
200
    """
201
    Admin API keys for full search service access.
202
    
203
    Attributes:
204
        primary_key (str): Primary admin key for full service access
205
        secondary_key (str): Secondary admin key for full service access
206
    """
207
```
208

209
### QueryKey
210

211
Individual query API key for read-only search access.
212

213
```python { .api }
214
class QueryKey:
215
    """
216
    Query API key for read-only search operations.
217
    
218
    Attributes:
219
        name (str): Descriptive name assigned to the key
220
        key (str): The actual API key value used for authentication
221
    """
222
```
223

224
### AdminKeyKind
225

226
Enumeration specifying which admin key to regenerate.
227

228
```python { .api }
229
class AdminKeyKind(str, Enum):
230
    """Admin key types for regeneration operations."""
231
    PRIMARY = "primary"
232
    SECONDARY = "secondary"
233
```
234

235
## Key Management Best Practices
236

237
### Admin Key Rotation
238

239
```python
240
# Safe admin key rotation pattern
241
# Step 1: Applications should use secondary key
242
current_keys = client.admin_keys.get("rg", "service")
243
print(f"Use secondary key in apps: {current_keys.secondary_key}")
244

245
# Step 2: Regenerate primary key
246
new_keys = client.admin_keys.regenerate("rg", "service", AdminKeyKind.PRIMARY)
247
print(f"New primary key: {new_keys.primary_key}")
248

249
# Step 3: Update applications to use new primary key
250
# Step 4: Regenerate secondary key
251
final_keys = client.admin_keys.regenerate("rg", "service", AdminKeyKind.SECONDARY)
252
print(f"Both keys rotated successfully")
253
```
254

255
### Query Key Management
256

257
```python
258
# Create application-specific query keys
259
apps = ["web-frontend", "mobile-app", "reporting-service", "analytics-dashboard"]
260
created_keys = {}
261

262
for app_name in apps:
263
    key = client.query_keys.create("rg", "service", app_name)
264
    created_keys[app_name] = key.key
265
    print(f"Created key for {app_name}: {key.key}")
266

267
# Later: Remove access for specific application
268
app_to_remove = "analytics-dashboard"
269
if app_to_remove in created_keys:
270
    client.query_keys.delete("rg", "service", created_keys[app_to_remove])
271
    print(f"Removed access for {app_to_remove}")
272
```
273

274
### Key Usage Scenarios
275

276
**Admin Keys** are used for:
277
- Index creation, updating, and deletion
278
- Data upload and document management
279
- Service configuration changes
280
- Creating and managing data sources and indexers
281
- Managing skillsets and synonym maps
282

283
**Query Keys** are used for:
284
- Search requests (`POST /indexes/{index}/docs/search`)
285
- Lookup requests (`GET /indexes/{index}/docs/{key}`)
286
- Suggest requests (`POST /indexes/{index}/docs/suggest`)
287
- Autocomplete requests (`POST /indexes/{index}/docs/autocomplete`)
288

289
### Security Considerations
290

291
```python
292
# Store keys securely - never in source code
293
import os
294
from azure.keyvault.secrets import SecretClient
295
from azure.identity import DefaultAzureCredential
296

297
# Store admin key in Key Vault
298
credential = DefaultAzureCredential()
299
kv_client = SecretClient("https://my-vault.vault.azure.net/", credential)
300

301
admin_keys = client.admin_keys.get("rg", "service")
302
kv_client.set_secret("search-admin-key", admin_keys.primary_key)
303

304
# Retrieve key when needed
305
admin_key = kv_client.get_secret("search-admin-key").value
306
```