added api docs

interface/api/verification/bodies/verification.yaml

@@ -0,0 +1,15 @@
+components:
+  requestBodies:
+    VerificationCodeBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/verification.yaml#/components/schemas/VerificationCodeRequest
+
+    VerifyCodeBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/verification.yaml#/components/schemas/CodeVerificationRequest

interface/api/verification/create.yaml

@@ -0,0 +1,34 @@
+post:
+  tags: [Verification, Auth]
+  summary: Request verification code
+  operationId: verificationRequestCode
+  security:
+    - bearerAuth: []
+  requestBody:
+    $ref: ./bodies/verification.yaml#/components/requestBodies/VerificationCodeBody
+  responses:
+    '202':
+      description: Verification code requested
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/verification.yaml#/components/schemas/VerificationResponseData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '429':
+      $ref: ../response/operation.yaml#/components/responses/TooManyRequests
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/verification/request/verification.yaml

@@ -0,0 +1,31 @@
+components:
+  schemas:
+    VerificationCodeRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - purpose
+        - idempotencyKey
+      properties:
+        purpose:
+          type: string
+          description: Verification purpose, e.g. login.
+        target:
+          type: string
+          format: email
+        idempotencyKey:
+          type: string
+
+    CodeVerificationRequest:
+      allOf:
+        - $ref: ./verification.yaml#/components/schemas/VerificationCodeRequest
+        - type: object
+          additionalProperties: false
+          required:
+            - code
+            - sessionIdentifier
+          properties:
+            code:
+              type: string
+            sessionIdentifier:
+              $ref: ../../../models/auth/session_identifier.yaml#/components/schemas/SessionIdentifier

interface/api/verification/resend.yaml

@@ -0,0 +1,34 @@
+post:
+  tags: [Verification, Auth]
+  summary: Resend verification code
+  operationId: verificationResendCode
+  security:
+    - bearerAuth: []
+  requestBody:
+    $ref: ./bodies/verification.yaml#/components/requestBodies/VerificationCodeBody
+  responses:
+    '202':
+      description: Verification code resent
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/verification.yaml#/components/schemas/VerificationResponseData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '429':
+      $ref: ../response/operation.yaml#/components/responses/TooManyRequests
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/verification/response/verification.yaml

@@ -0,0 +1,26 @@
+components:
+  schemas:
+    VerificationResponseData:
+      type: object
+      additionalProperties: false
+      required:
+        - idempotencyKey
+        - ttl_seconds
+        - cooldown_seconds
+        - target
+      properties:
+        idempotencyKey:
+          type: string
+        ttl_seconds:
+          type: integer
+          format: int32
+        cooldown_seconds:
+          type: integer
+          format: int32
+        target:
+          type: string
+
+    VerifyResultData:
+      oneOf:
+        - $ref: ../../accounts/response/auth.yaml#/components/schemas/LoginData
+        - $ref: ../../response/response.yaml#/components/schemas/SuccessResultData

interface/api/verification/verify.yaml

@@ -0,0 +1,34 @@
+post:
+  tags: [Verification, Auth]
+  summary: Verify code and complete pending flow
+  operationId: verificationVerifyCode
+  security:
+    - bearerAuth: []
+  requestBody:
+    $ref: ./bodies/verification.yaml#/components/requestBodies/VerifyCodeBody
+  responses:
+    '200':
+      description: Verification successful
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/verification.yaml#/components/schemas/VerifyResultData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '410':
+      $ref: ../response/operation.yaml#/components/responses/Gone
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError