Skip to content

Commit 380cfa8

Browse files
szabosteveszabosteve
committed
DOCS] Adds update cross cluster API k
ey API examples.
1 parent 2502a36 commit 380cfa8

File tree

2 files changed

+205
-0
lines changed

2 files changed

+205
-0
lines changed

‎docs/reference/elasticsearch/rest-apis/update-cc-api-key-examples.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
applies_to:
3+
stack: all
4+
navigation_title: Update cross-cluster API examples
5+
---
6+
# Update cross-cluster API key API examples
7+
8+
The [update cross-cluster API key API](https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-security-update-cross-cluster-api-key) updates the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access. This page shows you examples of using this API.
9+
10+
If you create a cross-cluster API key as follows:
11+
12+
```console
13+
POST /_security/cross_cluster/api_key
14+
{
15+
"name": "my-cross-cluster-api-key",
16+
"access": {
17+
"search": [
18+
{
19+
"names": ["logs*"]
20+
}
21+
]
22+
},
23+
"metadata": {
24+
"application": "search"
25+
}
26+
}
27+
```
28+
29+
A successful call returns a JSON structure that provides API key information. For example:
30+
31+
```console-result
32+
{
33+
"id": "VuaCfGcBCdbkQm-e5aOx",
34+
"name": "my-cross-cluster-api-key",
35+
"api_key": "ui2lp2axTNmsyakw9tvNnw",
36+
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
37+
}
38+
```
39+
40+
% TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
41+
% TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]
42+
% TESTRESPONSE[s/VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==/$body.encoded/]
43+
44+
Information of the API key, including its exact role descriptor can be inspected with the [Get API key API](https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-security-get-api-key).
45+
46+
```console
47+
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx
48+
```
49+
50+
% TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
51+
% TEST[continued]
52+
53+
A successful call returns a JSON structure that contains the information of the API key:
54+
55+
```js
56+
{
57+
"api_keys": [
58+
{
59+
"id": "VuaCfGcBCdbkQm-e5aOx",
60+
"name": "my-cross-cluster-api-key",
61+
"type": "cross_cluster",
62+
"creation": 1548550550158,
63+
"expiration": null,
64+
"invalidated": false,
65+
"username": "myuser",
66+
"realm": "native1",
67+
"metadata": {
68+
"application": "search"
69+
},
70+
"role_descriptors": {
71+
"cross_cluster": { <1>
72+
"cluster": [
73+
"cross_cluster_search"
74+
],
75+
"indices": [
76+
{
77+
"names": [
78+
"logs*"
79+
],
80+
"privileges": [
81+
"read", "read_cross_cluster", "view_index_metadata"
82+
],
83+
"allow_restricted_indices": false
84+
}
85+
],
86+
"applications": [ ],
87+
"run_as": [ ],
88+
"metadata": { },
89+
"transient_metadata": {
90+
"enabled": true
91+
}
92+
}
93+
},
94+
"access": { <2>
95+
"search": [
96+
{
97+
"names": [
98+
"logs*"
99+
],
100+
"allow_restricted_indices": false
101+
}
102+
]
103+
}
104+
}
105+
]
106+
}
107+
```
108+
109+
% NOTCONSOLE
110+
111+
<1> Role descriptor corresponding to the specified `access` scope at creation time.
112+
In this example, it grants cross cluster search permission for the `logs*` index pattern.
113+
<2> The `access` corresponds to the value specified at API key creation time.
114+
115+
The following example updates the API key created above, assigning it new access scope and metadata:
116+
117+
```console
118+
PUT /_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx
119+
{
120+
"access": {
121+
"replication": [
122+
{
123+
"names": ["archive"]
124+
}
125+
]
126+
},
127+
"metadata": {
128+
"application": "replication"
129+
}
130+
}
131+
```
132+
133+
% TEST[s/VuaCfGcBCdbkQm-e5aOx/\${body.api_keys.0.id}/]
134+
% TEST[continued]
135+
136+
A successful call returns a JSON structure indicating that the API key was updated:
137+
138+
```console-result
139+
{
140+
"updated": true
141+
}
142+
```
143+
144+
The API key's permissions after the update can be inspected again with the [Get API key API](https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-security-get-api-key) and it will be:
145+
146+
```js
147+
{
148+
"api_keys": [
149+
{
150+
"id": "VuaCfGcBCdbkQm-e5aOx",
151+
"name": "my-cross-cluster-api-key",
152+
"type": "cross_cluster",
153+
"creation": 1548550550158,
154+
"expiration": null,
155+
"invalidated": false,
156+
"username": "myuser",
157+
"realm": "native1",
158+
"metadata": {
159+
"application": "replication"
160+
},
161+
"role_descriptors": {
162+
"cross_cluster": { <1>
163+
"cluster": [
164+
"cross_cluster_replication"
165+
],
166+
"indices": [
167+
{
168+
"names": [
169+
"archive*"
170+
],
171+
"privileges": [
172+
"cross_cluster_replication", "cross_cluster_replication_internal"
173+
],
174+
"allow_restricted_indices": false
175+
}
176+
],
177+
"applications": [ ],
178+
"run_as": [ ],
179+
"metadata": { },
180+
"transient_metadata": {
181+
"enabled": true
182+
}
183+
}
184+
},
185+
"access": { <2>
186+
"replication": [
187+
{
188+
"names": [
189+
"archive*"
190+
],
191+
"allow_restricted_indices": false
192+
}
193+
]
194+
}
195+
}
196+
]
197+
}
198+
199+
% NOTCONSOLE
200+
201+
<1> Role descriptor is updated to be the `access` scope specified at update time.
202+
In this example, it is updated to grant the cross cluster replication permission
203+
for the `archive*` index pattern.
204+
<2> The `access` corresponds to the value specified at API key update time.

‎docs/reference/elasticsearch/toc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@ toc:
104104
- file: rest-apis/searching-with-query-rules.md
105105
- file: rest-apis/shard-request-cache.md
106106
- file: rest-apis/term-vectors-examples.md
107+
- file: rest-apis/update-cc-api-key-examples.md
107108
- file: mapping-reference/index.md
108109
children:
109110
- file: mapping-reference/document-metadata-fields.md

0 commit comments

Comments
 (0)