API Keys - Determinist API Keys + Security changes (#148)

* Add an uid to make API Keys determinists, plus add a non-unique human readable name field to ease reading information * Describe errors for uid and name fields * Apply suggestions from code review Co-authored-by: Bruno Casali <[email protected]> * misc: add precisions * Reorganize route descriptions * Update error_code when API Key already exists for a given uid * Apply suggestions from code review Co-authored-by: Many the fish <[email protected]> * Add new keys actions, remove master-key changes, introduce a new error for immutable field and update tenant token * Update open-api spec * Update immutable_field error message * Apply suggestions from code review Co-authored-by: Many the fish <[email protected]> * Mention that the Default Admin API Key can manage keys * Specify that the JWT Tenant Token must be enrypted with the API Key value * Update the spec regarding the description of the Admin API Key to be up-to-date * Add uid_or_key url param to update and delete a key * Update text/0085-api-keys.md Co-authored-by: Many the fish <[email protected]> * Update text/0085-api-keys.md Co-authored-by: Many the fish <[email protected]> Co-authored-by: Bruno Casali <[email protected]> Co-authored-by: Many the fish <[email protected]> Co-authored-by: Kerollmops <[email protected]>
meilisearch · Jul 7, 2022 · 979b6ae · 979b6ae
1 parent fd4ee13
commit 979b6ae
Show file tree

Hide file tree

Showing 4 changed files with 424 additions and 442 deletions.
diff --git a/open-api.yaml b/open-api.yaml
@@ -562,9 +562,13 @@ components:
       title: key
       type: object
       properties:
+        uid:
+          type: string
+          description: A uuid v4 to identify the API Key. If not specified, it's generated by Meilisearch.
+          example: 01b4bc42-eb33-4041-b481-254d00cce834
         key:
           type: string
-          description: The generated key. Generated by Meilisearch.
+          description: The derived key to use in the Authorization header to authorize requests. Generated by Meilisearch with an HMAC, using an SHA-256 hash, of the uid and the master key.
           example: d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4
           readOnly: true
         actions:
@@ -589,12 +593,22 @@ components:
               - stats.get
               - dumps.create
               - version
+              - keys.get
+              - keys.create
+              - keys.update
+              - keys.delete
         indexes:
           type: array
           description: 'A list of accesible indexes permitted for the key. ["*"] for all indexes.'
           items:
             type: string
             example: movies
+        name:
+          type:
+            - string
+            - 'null'
+          description: A human-readable name for the key. null if empty.
+          default: null
         description:
           type:
             - string
@@ -622,7 +636,7 @@ components:
         - actions
         - indexes
         - expiresAt
-      description: API keys are stored and managed by the master key holder. These are the keys used by the technical teams to interact with Meilisearch at the level of the client/server code. API keys can have restrictions on which methods can be accessed via an actions list; they can also expiresAt a specific date time and be restricted to a specific set of indexes.
+      description: API keys are stored and managed by the master key holder and the default admin key holder. These are the keys used by the technical teams to interact with Meilisearch at the level of the client/server code. API keys can have restrictions on which methods can be accessed via an actions list; they can also expiresAt a specific date time and be restricted to a specific set of indexes.
   parameters:
     indexUid:
       name: indexUid
@@ -935,7 +949,7 @@ tags:
   - name: Keys
     description: |
       Manage API `keys` for a Meilisearch instance. Each key has a given set of permissions.
-      You must have the master key to access the `keys` route.
+      You must have the master key or the default admin key to access the `keys` route.
       [More information about the keys and their rights](https://docs.meilisearch.com/reference/features/security.html).
   - name: Settings
     description: |
@@ -2574,12 +2588,14 @@ paths:
                 example-1:
                   value:
                     results:
-                      - key: d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4
+                      - uid: 01b4bc42-eb33-4041-b481-254d00cce834
+                        key: d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4
+                        name: An API Key
+                        description: null
                         actions:
                           - documents.add
                         indexes:
                           - movies
-                        description: An API Key
                         expiresAt: '2022-11-12T10:00:00Z'
                         createdAt: '2021-11-12T10:00:00Z'
                         updatedAt: '2021-11-12T10:00:00Z'
@@ -2591,9 +2607,9 @@ paths:
       parameters:
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/offset'
-  '/keys/{key}':
-    get:
-      summary: Get an API key
+    post:
+      summary: Create an API Key
+      operationId: keys.create
       tags:
         - Keys
       security:
@@ -2606,40 +2622,38 @@ paths:
               schema:
                 $ref: '#/components/schemas/key'
               examples:
-                Fetch an API Key details:
+                Create an API Key:
                   value:
-                    description: Indexing Products API key
+                    uid: 01b4bc42-eb33-4041-b481-254d00cce834
                     key: d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4
+                    name: Indexing Products API key
+                    description: null
                     actions:
                       - documents.add
                     indexes:
                       - products
                     expiresAt: '2021-11-13T00:00:00Z'
                     createdAt: '2021-11-12T10:00:00Z'
                     updatedAt: '2021-11-12T10:00:00Z'
-      operationId: keys.get
-      description: Get an API Key
-    parameters:
-      - schema:
-          type: string
-        name: key
-        in: path
-        required: true
-        description: The API key value
-    delete:
-      summary: Delete an API key
-      operationId: keys.delete
-      tags:
-        - Keys
-      security:
-        - apiKey: []
-      responses:
-        '204':
-          $ref: '#/components/responses/204'
-      description: ''
-    patch:
-      summary: Update an API key
-      operationId: keys.update
+      parameters:
+        - $ref: '#/components/parameters/Content-Type'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/key'
+            examples:
+              API Key Creation:
+                value:
+                  name: Indexing Products API key
+                  actions:
+                    - documents.add
+                  indexes:
+                    - products
+                  expiresAt: '2021-11-13T00:00:00Z'
+  '/keys/{uid_or_key}':
+    get:
+      summary: Get an API key from its uid or key field.
       tags:
         - Keys
       security:
@@ -2652,32 +2666,42 @@ paths:
               schema:
                 $ref: '#/components/schemas/key'
               examples:
-                Patch an API Key Response:
+                Fetch an API Key details:
                   value:
-                    description: Indexing Products API key
+                    uid: 01b4bc42-eb33-4041-b481-254d00cce834
                     key: d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4
+                    name: Indexing Products API key
+                    description: null
                     actions:
                       - documents.add
                     indexes:
                       - products
                     expiresAt: '2021-11-13T00:00:00Z'
                     createdAt: '2021-11-12T10:00:00Z'
-                    updatedAt: '2021-11-12T15:00:00Z'
+                    updatedAt: '2021-11-12T10:00:00Z'
+      operationId: keys.get
+      description: Get an API Key
       parameters:
-        - $ref: '#/components/parameters/Content-Type'
-      description: Update an API Key
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/key'
-            examples:
-              Patch an API Key Request:
-                value:
-                  description: Indexing Products API key
-    post:
-      summary: Create an API Key
-      operationId: keys.create
+        - schema:
+            type: string
+          name: uidOrKey
+          in: path
+          required: true
+          description: The uid or the key field value of the API Key.
+    delete:
+      summary: Delete an API key specified by its uid or key field.
+      operationId: keys.delete
+      tags:
+        - Keys
+      security:
+        - apiKey: []
+      responses:
+        '204':
+          $ref: '#/components/responses/204'
+      description: ''
+    patch:
+      summary: Update an API key specified by its uid or key field.
+      operationId: keys.update
       tags:
         - Keys
       security:
@@ -2690,33 +2714,41 @@ paths:
               schema:
                 $ref: '#/components/schemas/key'
               examples:
-                Create an API Key:
+                Patch an API Key Response:
                   value:
-                    description: Indexing Products API key
+                    uid: 01b4bc42-eb33-4041-b481-254d00cce834
                     key: d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4
+                    name: Indexing Products API key
+                    description: null
                     actions:
                       - documents.add
                     indexes:
                       - products
                     expiresAt: '2021-11-13T00:00:00Z'
                     createdAt: '2021-11-12T10:00:00Z'
-                    updatedAt: '2021-11-12T10:00:00Z'
+                    updatedAt: '2021-11-12T15:00:00Z'
       parameters:
         - $ref: '#/components/parameters/Content-Type'
+      description: Update an API Key
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/key'
+              type: object
+              properties:
+                name:
+                  type:
+                    - string
+                    - 'null'
+                description:
+                  type:
+                    - string
+                    - 'null'
+              additionalProperties: false
             examples:
-              API Key Creation:
+              Patch an API Key Request:
                 value:
                   description: Indexing Products API key
-                  actions:
-                    - documents.add
-                  indexes:
-                    - products
-                  expiresAt: '2021-11-13T00:00:00Z'
   /stats:
     get:
       operationId: stats.list

diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md
@@ -122,6 +122,105 @@ HTTP Code: `400 Bad Request`
 
 ---
 
+## immutable_field
+
+`Synchronous` / `Asynchronous`
+
+### Context
+
+This error happens when an immutable field is given in a payload dedicated to modify a resource.
+
+### Error Definition
+
+HTTP Code: `400 Bad Request`
+
+```json
+{
+    "message": "The `:fieldName` field cannot be modified for the given resource.",
+    "code": "immutable_field",
+    "type": "invalid_request",
+    "link":"https://docs.meilisearch.com/errors#immutable_field"
+}
+```
+
+- The `:fieldName` is inferred when the message is generated.
+
+--
+
+## api_key_already_exists
+
+`Synchronous`
+
+### Context
+
+This error happens when a user tries to create an API Key that already exists for the given `uid`.
+
+### Error Definition
+
+HTTP Code: `409 Conflict`
+
+```json
+{
+    "message": "`uid` field value `:value` is already an existing API key.",
+    "code": "api_key_already_exists",
+    "type": "invalid_request",
+    "link": "https://docs.meilisearch.com/errors#api_key_already_exists"
+}
+```
+
+- The `:value` is inferred when the message is generated.
+
+---
+## invalid_api_key_uid
+
+`Synchronous`
+
+### Context
+
+This error happens when the `uid` field for an `API Key` resource is invalid.
+
+### Error Definition
+
+HTTP Code: `400 Bad Request`
+
+```json
+{
+    "message": "`uid` field value `:value` is invalid. It should be a valid UUID v4 string or omitted.",
+    "code": "invalid_api_key_uid",
+    "type": "invalid_request",
+    "link": "https://docs.meilisearch.com/errors#invalid_api_key_uid"
+}
+```
+
+- The `:value` is inferred when the message is generated.
+
+---
+
+## invalid_api_key_name
+
+`Synchronous`
+
+### Context
+
+This error happens when the `name` field for an `API Key` resource is invalid.
+
+### Error Definition
+
+HTTP Code: `400 Bad Request`
+
+```json
+{
+    "message": "`name` field value `:value` is invalid. It should be a string or specified as a null value.",
+    "code": "invalid_api_key_name",
+    "type": "invalid_request",
+    "link": "https://docs.meilisearch.com/errors#invalid_api_key_name"
+}
+```
+
+- The `:value` is inferred when the message is generated.
+
+---
+
 ## invalid_api_key_description
 
 `Synchronous`