From 6150f71ba1e0a3619fd500032712bd8548a976c3 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Wed, 3 May 2023 10:43:10 +0100
Subject: [PATCH] Corrections to the response format of
 `/_matrix/identity/v2/store-invite` (#1486)

This has been wrong since the dawn of time.

Fixes https://github.com/matrix-org/matrix-spec/issues/495
---
 .../newsfragments/1486.clarification          |  1 +
 data/api/identity/v2_store_invite.yaml        | 41 ++++++++++++++-----
 2 files changed, 31 insertions(+), 11 deletions(-)
 create mode 100644 changelogs/identity_service/newsfragments/1486.clarification

diff --git a/changelogs/identity_service/newsfragments/1486.clarification b/changelogs/identity_service/newsfragments/1486.clarification
new file mode 100644
index 00000000..c7372cc4
--- /dev/null
+++ b/changelogs/identity_service/newsfragments/1486.clarification
@@ -0,0 +1 @@
+Corrections to the response format of `/_matrix/identity/v2/store-invite`.
diff --git a/data/api/identity/v2_store_invite.yaml b/data/api/identity/v2_store_invite.yaml
index 86845eff..163081bb 100644
--- a/data/api/identity/v2_store_invite.yaml
+++ b/data/api/identity/v2_store_invite.yaml
@@ -142,20 +142,39 @@ paths:
                   A list of [server's long-term public key, generated ephemeral
                   public key].
                 items:
-                  type: string
+                  type: object
+                  title: PublicKey
+                  properties:
+                    public_key:
+                      type: string
+                      description: |
+                        The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
+                    key_validity_url:
+                      type: string
+                      description: |
+                        The URI of an endpoint where the validity of this key can be checked
+                        by passing it as a `public_key` query parameter. See
+                        [key management](/identity-service-api/#key-management).
+                  required: ['public_key', 'key_validity_url']
               display_name:
                 type: string
-                description: The generated (redacted) display_name.
+                description: The generated (redacted) display name.
             required: ['token', 'public_keys', 'display_name']
-            example:
-              application/json: {
-                "token": "sometoken",
-                "public_keys": [
-                  "serverpublickey",
-                  "ephemeralpublickey"
-                ],
-                "display_name": "f...@b..."
-              }
+          examples:
+            application/json: {
+              "token": "sometoken",
+              "public_keys": [
+                {
+                  "public_key": "serverPublicKeyBase64",
+                  "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid"
+                },
+                {
+                  "public_key": "ephemeralPublicKeyBase64",
+                  "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid"
+                }
+              ],
+              "display_name": "f...@b..."
+            }
         400:
           description: |
             An error has occurred.