[DOCS] Update API key API #88499
[DOCS] Update API key API #88499
Conversation
n1v0lg
added
>docs
| ==== | ||
| A call to this API might change the API key's access scope, even if you don't specify new | ||
| <<security-api-update-api-key-api-key-role-descriptors,`role_descriptors`>> in the request. | ||
| This behavior can occur if the owner user's permissions have changed since the creation or last update to the API key. |
There was a problem hiding this comment.
The preceding paragraph now explains that the user permissions snapshot is auto-updated so I've removed the now redundant explanation from the callout.
There was a problem hiding this comment.
LGTM
The content looks correct to me. I'll defer to @lockewritesdocs for polishing the writing. Thanks!
| It's not possible to update expired API keys, or API keys that have been invalidated by <<security-api-invalidate-api-key,invalidate API Key>>. | ||
|
|
||
| This API supports updates to an API key's access scope, i.e., its permissions, and its metadata. | ||
| The access scope of an API key is derived from the <<security-api-update-api-key-api-key-role-descriptors,`role_descriptors`>> you specify in the request, and a snapshot of the owner user's permissions at the time of the request. |
There was a problem hiding this comment.
We can be more explicit here. Instead of saying "is derived", we can just say "is an intersection of ...".
There was a problem hiding this comment.
I don't think "intersection of" is technically correct here without the disclaimer that when role_descriptors is empty (i.e., not assigned) it's not the intersection. I went with "derived" because it side-steps that problem, and references the role desc section where we accurately describe how the permissions are derived.
|
@elasticmachine update branch plz |
There was a problem hiding this comment.
Left a few suggested non-blocking changes. Thanks for iterating on this one @n1v0lg!
| The request body is optional. | ||
| Following parameters can be specified in it: |
There was a problem hiding this comment.
I don't think that we need the additional (Optional) tag. What if we changed this to read:
You can specify the following parameters in the request body, which is optional.
Each of the parameters have an (Optional) tag already, so I think that this statement highlights that the entire request body is optional without explicitly including an additional tag.
| } | ||
| ---- | ||
|
|
||
| The API key's effective permissions after the update will be the intersection of the supplied role descriptors and the <<security-api-update-api-key-examples-user-permissions, authenticated user's permissions>>: |
There was a problem hiding this comment.
+1 for including this information for now so that we have it somewhere. We can move it in a subsequent PR for creating an overview of API keys. Thanks @n1v0lg!
|
@elasticmachine run elasticsearch-ci/part-2 |
* upstream/master: (40 commits) Fix CI job naming [ML] disallow autoscaling downscaling in two trained model assignment scenarios (elastic#88623) Add "Vector Search" area to changelog schema [DOCS] Update API key API (elastic#88499) Enable the pipeline on the feature branch (elastic#88672) Adding the ability to register a PeerFinderListener to Coordinator (elastic#88626) [DOCS] Fix transform painless example syntax (elastic#88364) [ML] Muting InternalCategorizationAggregationTests testReduceRandom (elastic#88685) Fix double rounding errors for disk usage (elastic#88683) Replace health request with a state observer. (elastic#88641) [ML] Fail model deployment if all allocations cannot be provided (elastic#88656) Upgrade to OpenJDK 18.0.2+9 (elastic#88675) [ML] make bucket_correlation aggregation generally available (elastic#88655) Adding cardinality support for random_sampler agg (elastic#86838) Use custom task instead of generic AckedClusterStateUpdateTask (elastic#88643) Reinstate test cluster throttling behavior (elastic#88664) Mute testReadBlobWithPrematureConnectionClose Simplify plugin descriptor tests (elastic#88659) Add CI job for testing more job parallelism [ML] make deployment infer requests fully cancellable (elastic#88649) ...
API docs for the new
PUT /_security/api_key/<id>API.Link to doc preview.