API Keys - Determinist API Keys + Security changes

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

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`