From 578f9f3562e28a2589abd8f77ac2121f46ced2da Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 16:51:16 +0400 Subject: [PATCH 01/28] v0.28: API key updates --- .code-samples.meilisearch.yaml | 14 +++--------- learn/security/master_api_keys.md | 18 +++++++++------ reference/api/keys.md | 38 +++++++++++++++++++++++-------- 3 files changed, 43 insertions(+), 27 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..2372947445 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -116,16 +116,8 @@ update_a_key_1: |- -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ --data-binary '{ - "description": "Manage documents: Products/Reviews API key", - "actions": [ - "documents.add", - "documents.delete" - ], - "indexes": [ - "products", - "reviews" - ], - "expiresAt": "2042-04-02T00:42:42Z" + "name": "Products/Reviews API key", + "description": "Manage documents: Products/Reviews API key" }' delete_a_key_1: |- curl \ @@ -786,7 +778,7 @@ security_guide_update_key_1: |- -X PATCH 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ - --data-binary '{ "indexes": ["doctors"] }' + --data-binary '{ "name": "Default Search API Key" }' security_guide_create_key_1: |- curl \ -X POST 'http://localhost:7700/keys' \ diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index cff165cde6..cec2191fd7 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -82,15 +82,19 @@ Exposing your master key can give malicious users complete control over your Mei Meilisearch gives you fine-grained control over which users can access which indexes, endpoints, and routes. When protecting your instance with a master key, you can ensure only authorized users can carry out sensitive tasks such as adding documents or altering index settings. -The master key is the only key with access to the [`/keys` route](/reference/api/keys.md). This route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. +You can access to the [`/keys` route](/reference/api/keys.md) with the master key or an API key with containing `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. This route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. + +::: note +If you change your master key, the `key` field is re-generated. +::: Though the default API keys are usually enough to manage the security needs of most applications, this might not be the case when dealing with privacy-sensitive data. In these situations, the fine-grained control offered by the `/keys` endpoint allows you to clearly decide who can access what information and for how long. ### Updating an API key -You can freely update an API key at any time, even after it expires. This includes editing the indexes, endpoints, and routes it can access, as well as its description and expiry date. +You can freely update the `name` and `description` of an API key at any time, even after it expires. -We can update the `Default Search API Key` so regular users cannot perform search operations in our `patient_medical_records` index: +We can update the `Default Search API Key` to add a description: @@ -110,13 +114,13 @@ We can update the `Default Search API Key` so regular users cannot perform searc } ``` -To update an API key, you must use the [update API key endpoint](/reference/api/keys.md#update-a-key) which can only be accessed with the master key. +To update an API key, you must use the [update API key endpoint](/reference/api/keys.md#update-a-key), which can only be accessed with the master key or an API key containing the `keys.update` action. -Meilisearch supports partial updates with the `PATCH` route. This means your payload only needs to contain the data you want to update—in this case, `indexes`. +Meilisearch supports partial updates with the `PATCH` route. This means your payload only needs to contain the data you want to update—in this case, `description`. ### Creating an API key -You can create API keys by using the [create key endpoint](/reference/api/keys.md#create-a-key). This endpoint is always protected and can only be accessed with the master key. +You can create API keys by using the [create key endpoint](/reference/api/keys.md#create-a-key). This endpoint is always protected and can only be accessed with the master key or an API key with the `keys.create` action. Since we have altered the permissions in our default search key, we need to create a new API key so authorized users can search through out `patient_medical_records` index: @@ -146,7 +150,7 @@ It is good practice to always set an expiry date when creating a new API key. If You can use the [list keys endpoint](/reference/api/keys.md) to obtain information on any active key in your Meilisearch instance. This is useful when you need an overview of existing keys and their permissions. -[`GET /keys`](/reference/api/keys.md#get-all-keys) returns a full list of all existing keys. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you need the master key to access this endpoint. +[`GET /keys`](/reference/api/keys.md#get-all-keys) returns a full list of all existing keys. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. [`GET /keys/{key}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key}` should be replaced with the full `key` value obtained during key creation. diff --git a/reference/api/keys.md b/reference/api/keys.md index a6582e1f69..248fa30d1a 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,12 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request: - -```bash -curl \ - -H 'Authorization: Bearer MASTER_KEY' - … -``` +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request or your API key must have the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). @@ -74,13 +68,21 @@ List all existing API keys. **Expired keys are included in the response**, but d ### Returned fields +#### `name` + +A human-readable name for the key. Default value is `null`. + #### `description` A description for the key. Default value is `null`. +#### `uid` + +A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API Key. If not specified, it is generated by Meilisearch. + #### `key` -An alphanumeric key value generated by Meilisearch on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). +An alphanumeric key value generated by Meilisearch with an HMAC using an SHA-256 hash of the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. @@ -146,6 +148,20 @@ Only the `indexes`, `actions`, and `expiresAt` fields are mandatory. ### Body +#### `name` + +**Type:** string +**Default value:** `null` + +A human-readable name for the key. + +#### `uid` + +**Type:** string +**Default value:** none + +A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API Key. If not specified, it is generated by Meilisearch. + #### `description` **Type:** string @@ -177,6 +193,10 @@ A list of API actions permitted for the key. `["*"]` for all actions. | dumps.create | Provides access to the [create dump](/reference/api/dump.md#create-a-dump) endpoint. **Not restricted by `indexes`.** | | dumps.get | Provides access to the [get dump status](/reference/api/dump.md#get-dump-status) endpoint. **Not restricted by `indexes`.** | | version | Provides access to the [get Meilisearch version](/reference/api/version.md#get-version-of-meilisearch) endpoint. | +| keys.get | Provides access to the [get all keys](#get-all-keys) endpoint.| +| keys.create | Provides access to the [create key](#create-a-key) endpoint.| +| keys.update | Provides access to the [update keys](#update-a-key) endpoint.| +| keys.delete | Provides access to the [delete keys](#delete-a-key) endpoint.| #### `indexes` @@ -220,7 +240,7 @@ Date and time when the key will expire, represented in RFC 3339 format. `null` i -Update the description, permissions, or expiration date of an API key. A valid API [key](/reference/api/keys.md#key) is required. +Update the name and description of an API key. A valid API [key](/reference/api/keys.md#key) is required. To learn more about the variables sent in the body of the request, see the [create key](#body) endpoint. From e9d805e39ba1937a70bd95127d95dae41594cd21 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 17:37:32 +0400 Subject: [PATCH 02/28] update errors+tenant tokens --- learn/security/tenant_tokens.md | 10 +++++----- reference/api/error_codes.md | 16 ++++++++++++++++ 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/learn/security/tenant_tokens.md b/learn/security/tenant_tokens.md index 21939b7087..a88afbec2e 100644 --- a/learn/security/tenant_tokens.md +++ b/learn/security/tenant_tokens.md @@ -66,18 +66,18 @@ const tokenPayload = { 'filter': `user_id = ${currentUserID}` } }, - apiKeyPrefix: apiKey.substring(0, 8), + apiKeyUid: apiKey.substring(0, 8), exp: parseInt(Date.now() / 1000) + 20 * 60 // 20 minutes }; const token = jwt.sign(tokenPayload, apiKey, {algorithm: 'HS256'}); ``` -`tokenPayload` contains the token payload. It must contain three fields: `searchRules`, `apiKeyPrefix`, and `exp`. +`tokenPayload` contains the token payload. It must contain three fields: `searchRules`, `apiKeyUid`, and `exp`. `searchRules` must be a JSON object containing a set of search rules. These rules specify restrictions applied to every query using this web token. -`apiKeyPrefix` must be the first 8 characters of a valid Meilisearch API key. +`apiKeyUid` must be the `uid` of a valid Meilisearch API key. `exp` is the only optional parameter of a tenant token. It must be a UNIX timestamp specifying the expiration date of the token. @@ -117,7 +117,7 @@ The token payload contains most of the relevant token data. It must be an object ```json { "exp": 1646756934, - "apiKeyPrefix": "12345678", + "apiKeyUid": "12345678", "searchRules": { "patient_medical_records": { "filter": "user_id = 1" @@ -188,7 +188,7 @@ The previous rules can be combined in one tenant token: ```json { - "apiKeyPrefix": "rkDxFUHd", + "apiKeyUid": "rkDxFUHd", "exp": 1641835850, "searchRules": { "*": { diff --git a/reference/api/error_codes.md b/reference/api/error_codes.md index 0dcc2b22e9..3b97e2c630 100644 --- a/reference/api/error_codes.md +++ b/reference/api/error_codes.md @@ -168,3 +168,19 @@ The requested task does not exist. Please ensure that you are using the correct ### `invalid_typo_tolerance_min_word_size_for_typos` The `minWordSizeForTypos` object is invalid. The value for both `oneTypo` and `twoTypos` should be between `0` and `255`, and `twoTypos` should be greater or equal to `oneTypo`. + +### `immutable_field` + +The field you are trying to modify is immutable. + +### `api_key_already_exists` + +A key with this `uid` already exists. + +### `invalid_api_key_uid` + +The given `uid` is invalid. The `uid` must follow the [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) format. + +### `invalid_api_key_name` + +The give `name` is invalid. It should either be a string or `null`. \ No newline at end of file From 44ca0850049e34f56a01e60bf447d719642e5401 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 17:46:29 +0400 Subject: [PATCH 03/28] update keys.md --- reference/api/error_codes.md | 2 +- reference/api/keys.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/reference/api/error_codes.md b/reference/api/error_codes.md index 3b97e2c630..8af92c036a 100644 --- a/reference/api/error_codes.md +++ b/reference/api/error_codes.md @@ -183,4 +183,4 @@ The given `uid` is invalid. The `uid` must follow the [uuid v4](https://www.soha ### `invalid_api_key_name` -The give `name` is invalid. It should either be a string or `null`. \ No newline at end of file +The give `name` is invalid. It should either be a string or `null`. diff --git a/reference/api/keys.md b/reference/api/keys.md index 248fa30d1a..75f0cbd385 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request or your API key must have the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or your API key must contain the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). @@ -82,7 +82,7 @@ A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the #### `key` -An alphanumeric key value generated by Meilisearch with an HMAC using an SHA-256 hash of the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). +An alphanumeric key value generated by Meilisearch using the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. @@ -238,9 +238,9 @@ Date and time when the key will expire, represented in RFC 3339 format. `null` i ## Update a key - + -Update the name and description of an API key. A valid API [key](/reference/api/keys.md#key) is required. +Update the name and description of an API key. A valid API [uid](/reference/api/keys.md#key) is required. To learn more about the variables sent in the body of the request, see the [create key](#body) endpoint. @@ -272,9 +272,9 @@ Updates to keys are **partial**. This means you should provide only the fields y ## Delete a key - + -Delete the specified API key. A valid API [key](/reference/api/keys.md#key) is required. +Delete the specified API key. A valid API [uid](/reference/api/keys.md#uid) is required. ### Example From 8b620830bc123c6b55c8813c21c7f480d34e06f7 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 16 Jun 2022 18:21:30 +0400 Subject: [PATCH 04/28] pagination basics --- learn/security/master_api_keys.md | 4 ++-- reference/api/keys.md | 25 ++++++++++++++++++++++--- 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index cec2191fd7..57a2dc0643 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -82,7 +82,7 @@ Exposing your master key can give malicious users complete control over your Mei Meilisearch gives you fine-grained control over which users can access which indexes, endpoints, and routes. When protecting your instance with a master key, you can ensure only authorized users can carry out sensitive tasks such as adding documents or altering index settings. -You can access to the [`/keys` route](/reference/api/keys.md) with the master key or an API key with containing `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. This route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. +You can access the [`/keys` route](/reference/api/keys.md) using the master key or an API key containing `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. This route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. ::: note If you change your master key, the `key` field is re-generated. @@ -92,7 +92,7 @@ Though the default API keys are usually enough to manage the security needs of m ### Updating an API key -You can freely update the `name` and `description` of an API key at any time, even after it expires. +You can update the `name` and `description` of an API key at any time, even after it expires. We can update the `Default Search API Key` to add a description: diff --git a/reference/api/keys.md b/reference/api/keys.md index 75f0cbd385..3327bda3ff 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -62,10 +62,17 @@ List all existing API keys. **Expired keys are included in the response**, but d "createdAt": "2021-08-11T10:00:00Z", "updatedAt": "2021-08-11T10:00:00Z" } - ] + ], + "offset":0, + "limit":20, + "total":7 } ``` +::: note +API keys are displayed in descending order based on their `createdAt` date. This means that the most recently created keys appear first. +::: + ### Returned fields #### `name` @@ -108,11 +115,23 @@ Date and time when the key was created, represented in RFC 3339 format. Date and time when the key was last updated, represented in RFC 3339 format. +### `offset` + +Sets the starting point in the results, effectively skipping over a given number of API keys. + +### `limit` + +Sets the maximum number of documents to be returned by the current request. + +### `total` + +Gives the total number of API keys that can be browsed. + ## Get one key - + -Get information on the specified key. Attempting to use this endpoint with a non-existent or deleted key will result in [an error](/reference/api/error_codes.md#api-key-not-found). A valid API [key](/reference/api/keys.md#key) is required. +Get information on the specified key. Attempting to use this endpoint with a non-existent or deleted key will result in [an error](/reference/api/error_codes.md#api-key-not-found). A valid API [key](/reference/api/keys.md#key) or [uid](/reference/api/keys.md#uid) is required. ### Example From 318977f7f36475001abab0cdb6e7fefedc39d197 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Mon, 20 Jun 2022 17:34:22 +0400 Subject: [PATCH 05/28] add pagination+other updates --- .code-samples.meilisearch.yaml | 8 ++--- learn/advanced/updating.md | 4 +++ learn/security/master_api_keys.md | 47 ++++++++++++++----------- reference/api/keys.md | 57 ++++++++++++++++++------------- 4 files changed, 69 insertions(+), 47 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 2372947445..3b3ec8cb32 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -97,7 +97,7 @@ get_one_key_1: |- -H 'Authorization: Bearer MASTER_KEY' get_all_keys_1: |- curl \ - -X GET 'http://localhost:7700/keys' \ + -X GET 'http://localhost:7700/keys?limit=3' \ -H 'Authorization: Bearer MASTER_KEY' create_a_key_1: |- curl \ @@ -775,10 +775,10 @@ security_guide_search_key_1: |- -H 'Authorization: Bearer API_KEY' security_guide_update_key_1: |- curl \ - -X PATCH 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X PATCH 'http://localhost:7700/keys/74c9c733-3368-4738-bbe5-1d18a5fecb37 \ -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ - --data-binary '{ "name": "Default Search API Key" }' + --data-binary '{ "description": "Default Search API Key" }' security_guide_create_key_1: |- curl \ -X POST 'http://localhost:7700/keys' \ @@ -796,7 +796,7 @@ security_guide_list_keys_1: |- -H 'Authorization: Bearer MASTER_KEY' security_guide_delete_key_1: |- curl \ - -X DELETE 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X DELETE 'http://localhost:7700/keys/ac5cd97d-5a4b-4226-a868-2d0eb6d197ab' \ -H 'Authorization: Bearer MASTER_KEY' primary_field_guide_create_index_primary_key: |- curl \ diff --git a/learn/advanced/updating.md b/learn/advanced/updating.md index 508f2a2969..6e15ff0d0e 100644 --- a/learn/advanced/updating.md +++ b/learn/advanced/updating.md @@ -102,6 +102,10 @@ docker run -it --rm \ :::: +:::note +If you are updating to v0.28, keys imported from the old version will have their `key` and `uid` fields regenerated. +::: + ### Proceed according to your database version Now that you know which Meilisearch version your database is compatible with, proceed accordingly: diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 57a2dc0643..817727ab60 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -82,31 +82,29 @@ Exposing your master key can give malicious users complete control over your Mei Meilisearch gives you fine-grained control over which users can access which indexes, endpoints, and routes. When protecting your instance with a master key, you can ensure only authorized users can carry out sensitive tasks such as adding documents or altering index settings. -You can access the [`/keys` route](/reference/api/keys.md) using the master key or an API key containing `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. This route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. - -::: note -If you change your master key, the `key` field is re-generated. -::: +You can access the [`/keys` route](/reference/api/keys.md) using the master key or an API key with access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. This `/keys` route allows you to [create](#creating-an-api-key), [update](#updating-an-api-key), [list](#listing-api-keys), and [delete](#deleting-an-api-key) API keys. Though the default API keys are usually enough to manage the security needs of most applications, this might not be the case when dealing with privacy-sensitive data. In these situations, the fine-grained control offered by the `/keys` endpoint allows you to clearly decide who can access what information and for how long. ### Updating an API key -You can update the `name` and `description` of an API key at any time, even after it expires. +You can only update the `name` and `description` of an API key, even after it expires. -We can update the `Default Search API Key` to add a description: +We can update the `Default Search API Key` to change the description: ```json { + "name": "Default Search API Key", "description": "Default Search API Key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid":"74c9c733-3368-4738-bbe5-1d18a5fecb37", "actions": [ "search" ], "indexes": [ - "doctors" + "*" ], "expiresAt": null, "createdAt": "2022-01-01T10:00:00Z", @@ -114,7 +112,7 @@ We can update the `Default Search API Key` to add a description: } ``` -To update an API key, you must use the [update API key endpoint](/reference/api/keys.md#update-a-key), which can only be accessed with the master key or an API key containing the `keys.update` action. +To update an API key, you must use the [update API key endpoint](/reference/api/keys.md#update-a-key), which can only be accessed with the master key or an API key with the `keys.update` action. Meilisearch supports partial updates with the `PATCH` route. This means your payload only needs to contain the data you want to update—in this case, `description`. @@ -122,7 +120,7 @@ Meilisearch supports partial updates with the `PATCH` route. This means your pay You can create API keys by using the [create key endpoint](/reference/api/keys.md#create-a-key). This endpoint is always protected and can only be accessed with the master key or an API key with the `keys.create` action. -Since we have altered the permissions in our default search key, we need to create a new API key so authorized users can search through out `patient_medical_records` index: +Let's create a new API key so authorized users can search through out `patient_medical_records` index: @@ -130,8 +128,10 @@ All [`/keys` endpoints](/reference/api/keys.md) are synchronous, so your key wil ```json { + "name": null, "description": "Search patient records key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab", "actions": [ "search" ], @@ -152,7 +152,7 @@ You can use the [list keys endpoint](/reference/api/keys.md) to obtain informati [`GET /keys`](/reference/api/keys.md#get-all-keys) returns a full list of all existing keys. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. -[`GET /keys/{key}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key}` should be replaced with the full `key` value obtained during key creation. +[`GET /keys/{key_or_uid}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key_or_uid}` should be replaced with the full `key` or `uid` value obtained during key creation. We can query our instance to confirm which active keys can search our `patient_medical_records` index: @@ -162,21 +162,25 @@ We can query our instance to confirm which active keys can search our `patient_m { "results": [ { - "description": "Default Search API Key (Use it to search from the frontend code)", - "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99", + "name": "Default Search API Key", + "description": "Default Search API Key", + "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid":"74c9c733-3368-4738-bbe5-1d18a5fecb37", "actions": [ - "search" + "search" ], "indexes": [ - "doctors" + "*" ], "expiresAt": null, - "createdAt": "2021-08-11T10:00:00Z", - "updatedAt": "2021-08-11T10:00:00Z" + "createdAt": "2022-01-01T10:00:00Z", + "updatedAt": "2022-01-01T10:00:00Z" }, { + "name": "Default Admin API Key", "description": "Default Admin API Key (Use it for all other operations. Caution! Do not share it on the client side)", "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f", + "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", "actions": [ "*" ], @@ -188,8 +192,10 @@ We can query our instance to confirm which active keys can search our `patient_m "updatedAt": "2021-08-11T10:00:00Z" }, { + "name": null, "description": "Search patient records key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab", "actions": [ "search" ], @@ -200,7 +206,10 @@ We can query our instance to confirm which active keys can search our `patient_m "createdAt": "2022-01-01T10:00:00Z", "updatedAt": "2022-01-01T10:00:00Z" } - ] + ], + "offset":0, + "limit":20, + "total":3 } ``` @@ -216,8 +225,6 @@ If we accidentally exposed our `Search patient records key`, we can delete it to Once a key is past its `expiresAt` date, using it for API authorization will return an error. Expired keys will still be returned by the [list keys endpoint](/reference/api/keys.md#get-all-keys). -If you must continue using an expired key, you may use the [update key endpoint](/reference/api/keys.md#update-a-key) to set a new `expiresAt` date and effectively reactivate it. - ## Changing the master key To change the master key, first terminate your Meilisearch instance. Then relaunch it, [supplying a new value for the master key](#protecting-a-meilisearch-instance). diff --git a/reference/api/keys.md b/reference/api/keys.md index 3327bda3ff..12d754d197 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or your API key must contain the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or your API key must have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). @@ -12,6 +12,13 @@ List all existing API keys. **Expired keys are included in the response**, but d [See below for an explanation of returned fields.](#description) +#### Query parameters + +| Query Parameter | Description | Default Value | +| ------------------------ | --------------------------| ------------- | +| **offset** | number of keys to skip | 0 | +| **limit** | number of keys to return | 20 | + ### Example @@ -64,7 +71,7 @@ List all existing API keys. **Expired keys are included in the response**, but d } ], "offset":0, - "limit":20, + "limit":3, "total":7 } ``` @@ -75,6 +82,24 @@ API keys are displayed in descending order based on their `createdAt` date. This ### Returned fields +Returns API keys in an array called `results`, along with the following fields: + +#### `offset` + +The number of keys skipped over. + +#### `limit` + +The maximum number of keys to be returned by the request. + +#### `total` + +The total number of API keys that can be browsed. + +### The `results` array + +For each key, it returns: + #### `name` A human-readable name for the key. Default value is `null`. @@ -85,7 +110,7 @@ A description for the key. Default value is `null`. #### `uid` -A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API Key. If not specified, it is generated by Meilisearch. +A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API key. If not specified, it is generated by Meilisearch. #### `key` @@ -115,21 +140,9 @@ Date and time when the key was created, represented in RFC 3339 format. Date and time when the key was last updated, represented in RFC 3339 format. -### `offset` - -Sets the starting point in the results, effectively skipping over a given number of API keys. - -### `limit` - -Sets the maximum number of documents to be returned by the current request. - -### `total` - -Gives the total number of API keys that can be browsed. - ## Get one key - + Get information on the specified key. Attempting to use this endpoint with a non-existent or deleted key will result in [an error](/reference/api/error_codes.md#api-key-not-found). A valid API [key](/reference/api/keys.md#key) or [uid](/reference/api/keys.md#uid) is required. @@ -179,7 +192,7 @@ A human-readable name for the key. **Type:** string **Default value:** none -A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API Key. If not specified, it is generated by Meilisearch. +A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API key. If not specified, it is generated by Meilisearch. #### `description` @@ -214,8 +227,8 @@ A list of API actions permitted for the key. `["*"]` for all actions. | version | Provides access to the [get Meilisearch version](/reference/api/version.md#get-version-of-meilisearch) endpoint. | | keys.get | Provides access to the [get all keys](#get-all-keys) endpoint.| | keys.create | Provides access to the [create key](#create-a-key) endpoint.| -| keys.update | Provides access to the [update keys](#update-a-key) endpoint.| -| keys.delete | Provides access to the [delete keys](#delete-a-key) endpoint.| +| keys.update | Provides access to the [update key](#update-a-key) endpoint.| +| keys.delete | Provides access to the [delete key](#delete-a-key) endpoint.| #### `indexes` @@ -276,12 +289,10 @@ Updates to keys are **partial**. This means you should provide only the fields y "description": "Manage documents: Products/Reviews API key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", "actions": [ - "documents.add", - "documents.delete" + "documents.add" ], "indexes": [ - "products", - "reviews" + "products" ], "expiresAt": "2021-12-31T23:59:59Z", "createdAt": "2021-11-12T10:00:00Z", From ae2a4418cbf01e890caade7131bfa61d1ad7555b Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Mon, 20 Jun 2022 17:51:35 +0400 Subject: [PATCH 06/28] update code samples --- .code-samples.meilisearch.yaml | 4 ++-- reference/api/keys.md | 18 ++++++++++++++---- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 3b3ec8cb32..6c53c49064 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -112,7 +112,7 @@ create_a_key_1: |- }' update_a_key_1: |- curl \ - -X PATCH 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X PATCH 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \ -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ --data-binary '{ @@ -121,7 +121,7 @@ update_a_key_1: |- }' delete_a_key_1: |- curl \ - -X DELETE 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X DELETE 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \ -H 'Authorization: Bearer MASTER_KEY' get_settings_1: |- curl \ diff --git a/reference/api/keys.md b/reference/api/keys.md index 12d754d197..1fbbb0791b 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -29,8 +29,10 @@ List all existing API keys. **Expired keys are included in the response**, but d { "results": [ { + "name": null, "description": "Manage documents: Products/Reviews API key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", "actions": [ "documents.add", "documents.delete" @@ -44,8 +46,10 @@ List all existing API keys. **Expired keys are included in the response**, but d "updatedAt": "2021-10-13T15:00:00Z" }, { + "name": "Default Search API Key", "description": "Default Search API Key (Use it to search from the frontend code)", "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99", + "uid": "74c9c733-3368-4738-bbe5-1d18a5fecb37", "actions": [ "search" ], @@ -57,8 +61,10 @@ List all existing API keys. **Expired keys are included in the response**, but d "updatedAt": "2021-08-11T10:00:00Z" }, { + "name": "Default Admin API Key", "description": "Default Admin API Key (Use it for all other operations. Caution! Do not share it on the client side)", "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f", + "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", "actions": [ "*" ], @@ -286,17 +292,21 @@ Updates to keys are **partial**. This means you should provide only the fields y ```json { + "name": "Products/Reviews API key", "description": "Manage documents: Products/Reviews API key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", "actions": [ - "documents.add" + "documents.add", + "documents.delete" ], "indexes": [ - "products" + "products", + "reviews" ], "expiresAt": "2021-12-31T23:59:59Z", - "createdAt": "2021-11-12T10:00:00Z", - "updatedAt": "2021-10-12T15:00:00Z" + "createdAt": "2021-10-12T00:00:00Z", + "updatedAt": "2021-10-13T15:00:00Z" } ``` From 22385e52596b85d17a61c39ed1cfc3586b953d99 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Mon, 20 Jun 2022 18:03:51 +0400 Subject: [PATCH 07/28] update actions+indentation --- learn/security/master_api_keys.md | 6 +++--- reference/api/keys.md | 7 +++---- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 817727ab60..f4760a183c 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -180,12 +180,12 @@ We can query our instance to confirm which active keys can search our `patient_m "name": "Default Admin API Key", "description": "Default Admin API Key (Use it for all other operations. Caution! Do not share it on the client side)", "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f", - "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", + "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", "actions": [ - "*" + "*" ], "indexes": [ - "*" + "*" ], "expiresAt": null, "createdAt": "2021-08-11T10:00:00Z", diff --git a/reference/api/keys.md b/reference/api/keys.md index 1fbbb0791b..109a484e30 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or your API key must have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). @@ -229,7 +229,6 @@ A list of API actions permitted for the key. `["*"]` for all actions. | settings.update | Provides access to the [update settings](/reference/api/settings.md#update-settings) and [reset settings](/reference/api/settings.md#reset-settings) endpoints and equivalents for all subroutes on authorized indexes. | | stats.get | Provides access to the [get stats of an index](/reference/api/stats.md#get-stats-of-an-index) endpoint and the [get stats of all indexes](/reference/api/stats.md#get-stats-of-all-indexes) endpoint. For the latter, **non-authorized `indexes` are omitted from the response**. | | dumps.create | Provides access to the [create dump](/reference/api/dump.md#create-a-dump) endpoint. **Not restricted by `indexes`.** | -| dumps.get | Provides access to the [get dump status](/reference/api/dump.md#get-dump-status) endpoint. **Not restricted by `indexes`.** | | version | Provides access to the [get Meilisearch version](/reference/api/version.md#get-version-of-meilisearch) endpoint. | | keys.get | Provides access to the [get all keys](#get-all-keys) endpoint.| | keys.create | Provides access to the [create key](#create-a-key) endpoint.| @@ -263,10 +262,10 @@ Date and time when the key will expire, represented in RFC 3339 format. `null` i "description": "Add documents: Products API key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", "actions": [ - "documents.add" + "documents.add" ], "indexes": [ - "products" + "products" ], "expiresAt": "2021-11-13T00:00:00Z", "createdAt": "2021-11-12T10:00:00Z", From f727adbd6ab8017831b9c381e8a394416213b4e9 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Wed, 22 Jun 2022 17:11:06 +0400 Subject: [PATCH 08/28] Update keys.md --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 109a484e30..4b2e3ac9ee 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -8,7 +8,7 @@ The `/keys` route allows you to create, manage, and delete API keys. To use thes -List all existing API keys. **Expired keys are included in the response**, but deleted keys are not. +List all existing API keys. **Expired keys are included in the response**, but deleted keys are not. Results can be paginated by using the `offset` and `limit` query parameters. [See below for an explanation of returned fields.](#description) From 025f3325c6e1e5b086a87571cb6b3360a880908d Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 23 Jun 2022 17:48:43 +0400 Subject: [PATCH 09/28] Apply suggestions from code review Co-authored-by: gui machiavelli --- learn/security/master_api_keys.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index f4760a183c..5526c8108a 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -90,7 +90,7 @@ Though the default API keys are usually enough to manage the security needs of m You can only update the `name` and `description` of an API key, even after it expires. -We can update the `Default Search API Key` to change the description: +For example, we can update the `Default Search API Key` and change its description: @@ -163,7 +163,7 @@ We can query our instance to confirm which active keys can search our `patient_m "results": [ { "name": "Default Search API Key", - "description": "Default Search API Key", + "description": "Use it to search from the frontend", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", "uid":"74c9c733-3368-4738-bbe5-1d18a5fecb37", "actions": [ @@ -178,7 +178,7 @@ We can query our instance to confirm which active keys can search our `patient_m }, { "name": "Default Admin API Key", - "description": "Default Admin API Key (Use it for all other operations. Caution! Do not share it on the client side)", + "description": "Use it for all other than search operations. Caution! Do not expose it on a public frontend", "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f", "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", "actions": [ From cc00994bf18bae4ff886aa78393cdf15447bf113 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Thu, 23 Jun 2022 17:53:18 +0400 Subject: [PATCH 10/28] update based on feedback --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 4b2e3ac9ee..c0987ac998 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must either [set the master key](/learn/configuration/instance_options.md#master-key) and supply it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must first [set the master key](/learn/configuration/instance_options.md#master-key).Once a master key is set, you caan access these endpoints by and supplying it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). From 21880fca1e219186428a69c31606c1e60735e7ab Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 23 Jun 2022 17:53:53 +0400 Subject: [PATCH 11/28] Update reference/api/error_codes.md Co-authored-by: gui machiavelli --- reference/api/error_codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/error_codes.md b/reference/api/error_codes.md index 8af92c036a..9e52543da1 100644 --- a/reference/api/error_codes.md +++ b/reference/api/error_codes.md @@ -183,4 +183,4 @@ The given `uid` is invalid. The `uid` must follow the [uuid v4](https://www.soha ### `invalid_api_key_name` -The give `name` is invalid. It should either be a string or `null`. +The given `name` is invalid. It should either be a string or `null`. From 903d3cf28c431d92bcf344f677f9aba1573af08b Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 23 Jun 2022 17:58:48 +0400 Subject: [PATCH 12/28] Update reference/api/keys.md --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index c0987ac998..d64aa16d3d 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must first [set the master key](/learn/configuration/instance_options.md#master-key).Once a master key is set, you caan access these endpoints by and supplying it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must first [set the master key](/learn/configuration/instance_options.md#master-key). Once a master key is set, you can access these endpoints by supplying it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). From 95642d8f74770a03a42d52e544aa5fd2ae3cd543 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Thu, 23 Jun 2022 17:59:57 +0400 Subject: [PATCH 13/28] Update reference/api/keys.md --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index d64aa16d3d..22b72b237d 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -1,6 +1,6 @@ # Keys -The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must first [set the master key](/learn/configuration/instance_options.md#master-key). Once a master key is set, you can access these endpoints by supplying it in the header of the request, or use API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. +The `/keys` route allows you to create, manage, and delete API keys. To use these endpoints, you must first [set the master key](/learn/configuration/instance_options.md#master-key). Once a master key is set, you can access these endpoints by supplying it in the header of the request, or using API keys that have access to the `keys.get`, `keys.create`, `keys.update`, or `keys.delete` actions. [Learn more about managing keys and their rights](/learn/security/master_api_keys.md). From 5c28fbfbebf6097413b87892327e782b9d5039a7 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Tue, 28 Jun 2022 11:17:10 +0400 Subject: [PATCH 14/28] Apply suggestions from code review Co-authored-by: Guillaume Mourier --- reference/api/keys.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 22b72b237d..e1851fde7e 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -47,7 +47,7 @@ List all existing API keys. **Expired keys are included in the response**, but d }, { "name": "Default Search API Key", - "description": "Default Search API Key (Use it to search from the frontend code)", + "description": "Use it to search from the frontend code", "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99", "uid": "74c9c733-3368-4738-bbe5-1d18a5fecb37", "actions": [ @@ -62,7 +62,7 @@ List all existing API keys. **Expired keys are included in the response**, but d }, { "name": "Default Admin API Key", - "description": "Default Admin API Key (Use it for all other operations. Caution! Do not share it on the client side)", + "description": "Use it for anything that is not a search operation. Caution! Do not expose it on a public frontend", "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f", "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213", "actions": [ From e22cb293e4e95c439ea0f66913bd411ca22066b6 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 28 Jun 2022 11:57:24 +0400 Subject: [PATCH 15/28] update based on gmourier's review --- learn/security/master_api_keys.md | 2 +- learn/security/tenant_tokens.md | 4 ++-- reference/api/keys.md | 14 +++++++------- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 5526c8108a..02aa839dab 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -150,7 +150,7 @@ It is good practice to always set an expiry date when creating a new API key. If You can use the [list keys endpoint](/reference/api/keys.md) to obtain information on any active key in your Meilisearch instance. This is useful when you need an overview of existing keys and their permissions. -[`GET /keys`](/reference/api/keys.md#get-all-keys) returns a full list of all existing keys. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. +By default, [`GET /keys`](/reference/api/keys.md#get-all-keys) returns the most recently created 20 keys. You can change this using the [`limit`](/reference/api/keys.html#get-all-keys) query parameter. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. [`GET /keys/{key_or_uid}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key_or_uid}` should be replaced with the full `key` or `uid` value obtained during key creation. diff --git a/learn/security/tenant_tokens.md b/learn/security/tenant_tokens.md index a88afbec2e..86406e3bd7 100644 --- a/learn/security/tenant_tokens.md +++ b/learn/security/tenant_tokens.md @@ -117,7 +117,7 @@ The token payload contains most of the relevant token data. It must be an object ```json { "exp": 1646756934, - "apiKeyUid": "12345678", + "apiKeyUid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab", "searchRules": { "patient_medical_records": { "filter": "user_id = 1" @@ -188,7 +188,7 @@ The previous rules can be combined in one tenant token: ```json { - "apiKeyUid": "rkDxFUHd", + "apiKeyUid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab", "exp": 1641835850, "searchRules": { "*": { diff --git a/reference/api/keys.md b/reference/api/keys.md index e1851fde7e..35e41c2f8e 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -8,7 +8,7 @@ The `/keys` route allows you to create, manage, and delete API keys. To use thes -List all existing API keys. **Expired keys are included in the response**, but deleted keys are not. Results can be paginated by using the `offset` and `limit` query parameters. +List the most recently created 20 keys. **Expired keys are included in the response**, but deleted keys are not. Results can be paginated by using the `offset` and `limit` query parameters. [See below for an explanation of returned fields.](#description) @@ -16,8 +16,8 @@ List all existing API keys. **Expired keys are included in the response**, but d | Query Parameter | Description | Default Value | | ------------------------ | --------------------------| ------------- | -| **offset** | number of keys to skip | 0 | -| **limit** | number of keys to return | 20 | +| **offset** | Number of keys to skip | 0 | +| **limit** | Number of keys to return | 20 | ### Example @@ -275,9 +275,9 @@ Date and time when the key will expire, represented in RFC 3339 format. `null` i ## Update a key - + -Update the name and description of an API key. A valid API [uid](/reference/api/keys.md#key) is required. +Update the name and description of an API key. A valid API [key](/reference/api/keys.md#key) or [uid](/reference/api/keys.md#uid) is required. To learn more about the variables sent in the body of the request, see the [create key](#body) endpoint. @@ -311,9 +311,9 @@ Updates to keys are **partial**. This means you should provide only the fields y ## Delete a key - + -Delete the specified API key. A valid API [uid](/reference/api/keys.md#uid) is required. +Delete the specified API key. A valid API [key](/reference/api/keys.md#key) or [uid](/reference/api/keys.md#uid) is required. ### Example From a349772c10c6d4ff27af17b9fb9b4b909d3f9f8d Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 28 Jun 2022 11:59:25 +0400 Subject: [PATCH 16/28] fix link --- learn/security/master_api_keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 02aa839dab..23288e177b 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -150,7 +150,7 @@ It is good practice to always set an expiry date when creating a new API key. If You can use the [list keys endpoint](/reference/api/keys.md) to obtain information on any active key in your Meilisearch instance. This is useful when you need an overview of existing keys and their permissions. -By default, [`GET /keys`](/reference/api/keys.md#get-all-keys) returns the most recently created 20 keys. You can change this using the [`limit`](/reference/api/keys.html#get-all-keys) query parameter. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. +By default, [`GET /keys`](/reference/api/keys.md#get-all-keys) returns the most recently created 20 keys. You can change this using the [`limit`](/reference/api/keys.md#get-all-keys) query parameter. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. [`GET /keys/{key_or_uid}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key_or_uid}` should be replaced with the full `key` or `uid` value obtained during key creation. From 04b53a46bdb3d1fc83c3fa63d1883e4ec52ac22f Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 28 Jun 2022 17:23:11 +0400 Subject: [PATCH 17/28] update code sample --- learn/security/tenant_tokens.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/learn/security/tenant_tokens.md b/learn/security/tenant_tokens.md index 86406e3bd7..aff1e6c2fd 100644 --- a/learn/security/tenant_tokens.md +++ b/learn/security/tenant_tokens.md @@ -58,6 +58,7 @@ Using a third-party library for tenant token generation is fairly similar to cre const jwt = require('jsonwebtoken'); const apiKey = 'my_api_key'; +const apiKeyUid = 'ac5cd97d-5a4b-4226-a868-2d0eb6d197ab'; const currentUserID = 'a_user_id'; const tokenPayload = { @@ -66,7 +67,7 @@ const tokenPayload = { 'filter': `user_id = ${currentUserID}` } }, - apiKeyUid: apiKey.substring(0, 8), + apiKeyUid: apiKeyUid, exp: parseInt(Date.now() / 1000) + 20 * 60 // 20 minutes }; From eb937fb5616b40725cd9509e91eea1c4bd97abb6 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 29 Jun 2022 13:39:21 +0400 Subject: [PATCH 18/28] replace `uid` with `key` --- .code-samples.meilisearch.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 6c53c49064..92ff722538 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -112,7 +112,7 @@ create_a_key_1: |- }' update_a_key_1: |- curl \ - -X PATCH 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \ + -X PATCH 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ --data-binary '{ From c6215aea5fe0cc439473f095e5f697f6e4a5661a Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Wed, 29 Jun 2022 18:01:01 +0400 Subject: [PATCH 19/28] Apply suggestions from code review Co-authored-by: gui machiavelli --- learn/security/master_api_keys.md | 2 +- reference/api/keys.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 23288e177b..8f3c1ec36f 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -150,7 +150,7 @@ It is good practice to always set an expiry date when creating a new API key. If You can use the [list keys endpoint](/reference/api/keys.md) to obtain information on any active key in your Meilisearch instance. This is useful when you need an overview of existing keys and their permissions. -By default, [`GET /keys`](/reference/api/keys.md#get-all-keys) returns the most recently created 20 keys. You can change this using the [`limit`](/reference/api/keys.md#get-all-keys) query parameter. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. +By default, [`GET /keys`](/reference/api/keys.md#get-all-keys) returns the 20 most recently created keys. You can change this using the [`limit`](/reference/api/keys.md#get-all-keys) query parameter. **Expired keys will appear in the response, but deleted keys will not**. As with creating, deleting, and updating API keys, you either need the master key or an API key with the `keys.get` action to access this endpoint. [`GET /keys/{key_or_uid}`](/reference/api/keys.md#get-one-key) returns information on a single key. `{key_or_uid}` should be replaced with the full `key` or `uid` value obtained during key creation. diff --git a/reference/api/keys.md b/reference/api/keys.md index 35e41c2f8e..886e170682 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -8,7 +8,7 @@ The `/keys` route allows you to create, manage, and delete API keys. To use thes -List the most recently created 20 keys. **Expired keys are included in the response**, but deleted keys are not. Results can be paginated by using the `offset` and `limit` query parameters. +List the 20 most recently created keys. **Expired keys are included in the response**, but deleted keys are not. Results can be paginated by using the `offset` and `limit` query parameters. [See below for an explanation of returned fields.](#description) @@ -116,7 +116,7 @@ A description for the key. Default value is `null`. #### `uid` -A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API key. If not specified, it is generated by Meilisearch. +A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the API key. If not specified, it is automatically generated by Meilisearch. #### `key` From 9371bcb20abbe80d00be4038dd3cad9ee9e2952c Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 29 Jun 2022 18:20:08 +0400 Subject: [PATCH 20/28] update based on Gui's review --- reference/api/keys.md | 56 +++++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 886e170682..417f3d29c3 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -160,8 +160,10 @@ Get information on the specified key. Attempting to use this endpoint with a non ```json { + "name": null, "description": "Add documents: Products API key", "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", "actions": [ "documents.add" ], @@ -259,17 +261,19 @@ Date and time when the key will expire, represented in RFC 3339 format. `null` i ```json { - "description": "Add documents: Products API key", - "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", - "actions": [ - "documents.add" - ], - "indexes": [ - "products" - ], - "expiresAt": "2021-11-13T00:00:00Z", - "createdAt": "2021-11-12T10:00:00Z", - "updatedAt": "2021-11-12T10:00:00Z" + "name": null, + "description": "Manage documents: Products/Reviews API key", + "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", + "actions": [ + "documents.add" + ], + "indexes": [ + "products" + ], + "expiresAt": "2021-11-13T00:00:00Z", + "createdAt": "2021-11-12T10:00:00Z", + "updatedAt": "2021-11-12T10:00:00Z" } ``` @@ -291,21 +295,21 @@ Updates to keys are **partial**. This means you should provide only the fields y ```json { - "name": "Products/Reviews API key", - "description": "Manage documents: Products/Reviews API key", - "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", - "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", - "actions": [ - "documents.add", - "documents.delete" - ], - "indexes": [ - "products", - "reviews" - ], - "expiresAt": "2021-12-31T23:59:59Z", - "createdAt": "2021-10-12T00:00:00Z", - "updatedAt": "2021-10-13T15:00:00Z" + "name": "Products/Reviews API key", + "description": "Manage documents: Products/Reviews API key", + "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", + "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d", + "actions": [ + "documents.add", + "documents.delete" + ], + "indexes": [ + "products", + "reviews" + ], + "expiresAt": "2021-12-31T23:59:59Z", + "createdAt": "2021-10-12T00:00:00Z", + "updatedAt": "2021-10-13T15:00:00Z" } ``` From 82182c7af401749704f3a98751711fcbacde3e6a Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Sun, 3 Jul 2022 16:10:42 +0400 Subject: [PATCH 21/28] add note about deterministic keys --- reference/api/keys.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 8efdca4797..f1695ddadf 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -120,10 +120,14 @@ A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the #### `key` -An alphanumeric key value generated by Meilisearch using the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). +An alphanumeric key value generated by Meilisearch by hasing the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. +::: note +Since `key` is a hash of the `uid` and master key, `key` values are deterministic between instances sharing the same configuration. This means if the master key changes, all key values are automatically changed and that API key resources are propagated into dumps and snapshots without displaying the `key` field in clear. +::: + #### `actions` An array of API actions permitted for the key. `["*"]` for all actions. From 1727ede8d91fe0d12310e2f355e315f628bf331b Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Mon, 4 Jul 2022 23:18:45 +0400 Subject: [PATCH 22/28] Update reference/api/keys.md Co-authored-by: Many the fish --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index f1695ddadf..643b83e3c1 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -120,7 +120,7 @@ A [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) to identify the #### `key` -An alphanumeric key value generated by Meilisearch by hasing the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). +An alphanumeric key value generated by Meilisearch by hashing the `uid` and the master key on API key creation. Used for authorization when [making calls to a protected Meilisearch instance](/learn/security/master_api_keys.md#communicating-with-a-protected-instance). This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. From 17bc0747bf6e87e37a78e4019ac80823738474b5 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 5 Jul 2022 15:17:47 +0400 Subject: [PATCH 23/28] update note wording --- reference/api/keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 643b83e3c1..9f2fde25b5 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -125,7 +125,7 @@ An alphanumeric key value generated by Meilisearch by hashing the `uid` and the This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. ::: note -Since `key` is a hash of the `uid` and master key, `key` values are deterministic between instances sharing the same configuration. This means if the master key changes, all key values are automatically changed and that API key resources are propagated into dumps and snapshots without displaying the `key` field in clear. +Since `key` is a hash of the `uid` and master key, `key` values are deterministic between instances sharing the same configuration. This means if the master key changes, all `key` values are automatically changed. The `key` field is computed at runtime and therefore is not propagated to dumps and snapshots. Even if someone does have access to your dumps or snapshot, they cannot make malicious requests. ::: #### `actions` From 6f14c78492d9ed20664f76314b89541ad153d173 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 5 Jul 2022 16:07:21 +0400 Subject: [PATCH 24/28] update based on gui's review --- reference/api/keys.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/reference/api/keys.md b/reference/api/keys.md index 9f2fde25b5..082a3b506b 100644 --- a/reference/api/keys.md +++ b/reference/api/keys.md @@ -125,7 +125,9 @@ An alphanumeric key value generated by Meilisearch by hashing the `uid` and the This value is also used as the `{key}` path variable to [update](#update-a-key), [delete](#delete-a-key), or [get](#get-one-key) a specific key. ::: note -Since `key` is a hash of the `uid` and master key, `key` values are deterministic between instances sharing the same configuration. This means if the master key changes, all `key` values are automatically changed. The `key` field is computed at runtime and therefore is not propagated to dumps and snapshots. Even if someone does have access to your dumps or snapshot, they cannot make malicious requests. +Since `key` is a hash of the `uid` and master key, `key` values are deterministic between instances sharing the same configuration. This means if the master key changes, all `key` values are automatically changed. + +Since the `key` field depends on the master key, it is computed at runtime and therefore not propagated to dumps and snapshots. As a result, even if a malicious user comes into possession of your dumps or snapshots, they will not have access to your instance's API keys. ::: #### `actions` From 747d2e2c6fca067bdd62276e811395b1f39e8f6f Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Tue, 5 Jul 2022 21:53:28 +0400 Subject: [PATCH 25/28] update to add bash command --- learn/security/master_api_keys.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 8f3c1ec36f..83e45198f8 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -86,6 +86,14 @@ You can access the [`/keys` route](/reference/api/keys.md) using the master key Though the default API keys are usually enough to manage the security needs of most applications, this might not be the case when dealing with privacy-sensitive data. In these situations, the fine-grained control offered by the `/keys` endpoint allows you to clearly decide who can access what information and for how long. +The [`key`](/reference/api/keys.md#key) field is generated by hashing the master key and the [`uid`](/reference/api/keys.md#uid): + +```bash +echo -n $HYPHENATED_UUID | openssl dgst -sha256 -hmac $MASTER_KEY +``` + +As a result, `key` values are deterministic between instances sharing the same configuration. Since the `key` field depends on the master key, it is not propagated to dumps and snapshots. If a malicious user ever gets access to your dumps or snapshots, they will not have access to your instance's API keys. + ### Updating an API key You can only update the `name` and `description` of an API key, even after it expires. From 344a707a4f0368743aac8b4b5eb59568b1dfa6ee Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 6 Jul 2022 13:53:11 +0400 Subject: [PATCH 26/28] update based on gmourier's review --- learn/security/master_api_keys.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 83e45198f8..5f4179dc16 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -94,6 +94,8 @@ echo -n $HYPHENATED_UUID | openssl dgst -sha256 -hmac $MASTER_KEY As a result, `key` values are deterministic between instances sharing the same configuration. Since the `key` field depends on the master key, it is not propagated to dumps and snapshots. If a malicious user ever gets access to your dumps or snapshots, they will not have access to your instance's API keys. +This is also useful in continuous deployment processes as you know the value of the `key` field in advance. + ### Updating an API key You can only update the `name` and `description` of an API key, even after it expires. From 22d80322d26abe51aa2131157158c0ff3fb8f624 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 6 Jul 2022 15:32:03 +0400 Subject: [PATCH 27/28] update key `uid`s --- .code-samples.meilisearch.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index c42e2dc933..f162162d9f 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -99,7 +99,7 @@ get_all_tasks_paginating_2: |- -X GET 'http://localhost:7700/tasks?limit=2&from=8 get_one_key_1: |- curl \ - -X GET 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X GET 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \ -H 'Authorization: Bearer MASTER_KEY' get_all_keys_1: |- curl \ @@ -118,7 +118,7 @@ create_a_key_1: |- }' update_a_key_1: |- curl \ - -X PATCH 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \ + -X PATCH 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \ -H 'Authorization: Bearer MASTER_KEY' \ -H 'Content-Type: application/json' \ --data-binary '{ From 1f6241d891e735dad8f435eeb24bc7c71c57fe56 Mon Sep 17 00:00:00 2001 From: Maryam Sulemani Date: Wed, 6 Jul 2022 15:37:54 +0400 Subject: [PATCH 28/28] update based on gmourier's review --- learn/security/master_api_keys.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/learn/security/master_api_keys.md b/learn/security/master_api_keys.md index 5f4179dc16..45df62d8e9 100644 --- a/learn/security/master_api_keys.md +++ b/learn/security/master_api_keys.md @@ -86,14 +86,14 @@ You can access the [`/keys` route](/reference/api/keys.md) using the master key Though the default API keys are usually enough to manage the security needs of most applications, this might not be the case when dealing with privacy-sensitive data. In these situations, the fine-grained control offered by the `/keys` endpoint allows you to clearly decide who can access what information and for how long. -The [`key`](/reference/api/keys.md#key) field is generated by hashing the master key and the [`uid`](/reference/api/keys.md#uid): +The [`key`](/reference/api/keys.md#key) field is generated by hashing the master key and the [`uid`](/reference/api/keys.md#uid). As a result, `key` values are deterministic between instances sharing the same configuration. Since the `key` field depends on the master key, it is not propagated to dumps and snapshots. If a malicious user ever gets access to your dumps or snapshots, they will not have access to your instance's API keys. + +It is, therefore, possible to determine the value of the `key` field by using the following command: ```bash echo -n $HYPHENATED_UUID | openssl dgst -sha256 -hmac $MASTER_KEY ``` -As a result, `key` values are deterministic between instances sharing the same configuration. Since the `key` field depends on the master key, it is not propagated to dumps and snapshots. If a malicious user ever gets access to your dumps or snapshots, they will not have access to your instance's API keys. - This is also useful in continuous deployment processes as you know the value of the `key` field in advance. ### Updating an API key