From 191908e80937ac62900726cd9edc6845831a42ea Mon Sep 17 00:00:00 2001
From: David Wobrock <david.wobrock@backmarket.com>
Date: Fri, 27 Sep 2024 10:54:24 +0200
Subject: [PATCH] docs: add return_to query parameter to OAS Verification Flow
 for Native Apps

---
 selfservice/flow/verification/handler.go | 14 ++++++++++++++
 spec/api.json                            | 10 ++++++++++
 2 files changed, 24 insertions(+)

diff --git a/selfservice/flow/verification/handler.go b/selfservice/flow/verification/handler.go
index 8b0e832ad8e..785f627e7f6 100644
--- a/selfservice/flow/verification/handler.go
+++ b/selfservice/flow/verification/handler.go
@@ -123,6 +123,20 @@ func (h *Handler) NewVerificationFlow(w http.ResponseWriter, r *http.Request, ft
 	return f, nil
 }
 
+// Create Verification Flow Parameters for Native Apps
+//
+// swagger:parameters createNativeVerificationFlow
+//
+//nolint:deadcode,unused
+//lint:ignore U1000 Used to generate Swagger and OpenAPI definitions
+type createNativeVerificationFlow struct {
+	// A URL contained in the return_to key of the verification flow.
+	// This piece of data has no effect on the actual logic of the flow and is purely informational.
+	//
+	// in: query
+	ReturnTo string `json:"return_to"`
+}
+
 // swagger:route GET /self-service/verification/api frontend createNativeVerificationFlow
 //
 // # Create Verification Flow for Native Apps
diff --git a/spec/api.json b/spec/api.json
index 19726c4c1a5..d438cab3e7e 100644
--- a/spec/api.json
+++ b/spec/api.json
@@ -7092,6 +7092,16 @@
       "get": {
         "description": "This endpoint initiates a verification flow for API clients such as mobile devices, smart TVs, and so on.\n\nTo fetch an existing verification flow call `/self-service/verification/flows?flow=\u003cflow_id\u003e`.\n\nYou MUST NOT use this endpoint in client-side (Single Page Apps, ReactJS, AngularJS) nor server-side (Java Server\nPages, NodeJS, PHP, Golang, ...) browser applications. Using this endpoint in these applications will make\nyou vulnerable to a variety of CSRF attacks.\n\nThis endpoint MUST ONLY be used in scenarios such as native mobile apps (React Native, Objective C, Swift, Java, ...).\n\nMore information can be found at [Ory Email and Phone Verification Documentation](https://www.ory.sh/docs/kratos/self-service/flows/verify-email-account-activation).",
         "operationId": "createNativeVerificationFlow",
+        "parameters": [
+          {
+            "description": "A URL contained in the return_to key of the verification flow. This piece of data has no effect on the actual logic of the flow and is purely informational.",
+            "in": "query",
+            "name": "return_to",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
         "responses": {
           "200": {
             "content": {