semantics

src/openapi/container/abt-container-tokens.yaml

@@ -1,8 +1,8 @@
 openapi: 3.0.3
 info:
-  title: Integraion layer APIs for token storage for ABT
+  title: Integration layer APIs for token storage for ABT
   description: >-
-    APIs that give business processes access to the security and authorization state of a token within the scope of HTM. In the backend this is connected to a container which handles the accessToken en refreshToken management.
+    APIs that give business processes access to the security and authorization state of a token within the scope of HTM. In the backend this is connected to a container which handles the accessToken en refreshToken management for an OVpas as given by GBO.
   version: "1.0"
 servers:
   - url: https://services.acc.api.htm.nl/abt/containertokens/1.0
@@ -12,7 +12,6 @@ tags:
   - name: tokens
 paths:
   /tokens:
-    parameters: 
     post:
       tags:
         - tokens
@@ -27,18 +26,12 @@ paths:
               token:
                 value:
                   {
-                    "xTAT": "cf694905-7f76-4799-b0bc-490716921323",
+                    "xTat": "cf694905-7f76-4799-b0bc-490716921323",
                     "otpKey": "123456789123456789123456789abcde"
                   }
       responses:
         "201":
           description: Created               
-          content:
-            application/json:
-              schema:
-               $ref: "#/components/schemas/unavailable"
-              example:                
-                  "Ok"                
         "400":
           description: Bad Request
           content:
@@ -80,23 +73,39 @@ paths:
                     status: 404
                     title: Not Found
                     detail: TAT Account Not Found
+        "409":
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              examples:
+                TAT already exists:
+                  value:
+                    status: 409
+                    title: Conflict
+                    detail: TAT Account Token already exists
         "500":
           description: Internal server error
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-              example:
+              examples:
-                error: An unknown error has occurred
+                Internal Server Error:
-  /tokens/{xtat}/status:
+                  value:
+                    status: 500
+                    title: Internal Server Error
+                    detail: An unknown error has occurred
+  /tokens/{xTat}/status:
     parameters: 
-    - name: xtat
+    - name: xTat
       in: path
       schema:
         type: string
-        example: uuid
+        example: 85dbeacc-b9aa-4d5b-bdec-9319010c597f
       required: true
-      description: The xTAT for the token for which the status needs to be checked
+      description: The xTat for the token for which the status needs to be checked
     - name: customerProfileId
       in: query
       schema:
@@ -128,8 +137,8 @@ paths:
                   summary: Secured, not authorized
                   value:
                     {
-                      "isAuthorized": true,
+                      "isAuthorized": false,
-                      "isSecured": false
+                      "isSecured": true
                     }
                 Secured and authorized :
                   summary: Secured and authorized
@@ -185,17 +194,21 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-              example:
+              examples:
-                error: An unknown error has occurred
+                Internal Server Error:
-  /tokens/{xtat}:
+                  value:
+                    status: 500
+                    title: Internal Server Error
+                    detail: An unknown error has occurred
+  /tokens/{xTat}:
     parameters: 
-    - name: xtat
+    - name: xTat
       in: path
       schema:
         type: string
         example: uuid
       required: true
-      description: The xTAT for the token for which the status needs to be checked
+      description: The xTat for the token for which the status needs to be checked
     - name: customerProfileId
       in: query
       schema:
@@ -217,7 +230,7 @@ paths:
               token:
                 value:
                   {
-                    "otp": "1234564"
+                    "otp": "123456"
                   }
       responses:
         "200":
@@ -227,19 +240,19 @@ paths:
               schema:
                $ref: "#/components/schemas/TokenStatusResponse"
               examples:
-                Not secured, not authorized :
+                Not secured and not authorized :
                   summary: Not secured, not authorized
                   value:
                     {
                       "isAuthorized": false,
                       "isSecured": false
                     }
-              Secured, not authorized :
+                Secured and not authorized :
                   summary: Secured, not authorized
                   value:
                     {
-                      "isAuthorized": true,
+                      "isAuthorized": false,
-                      "isSecured": false
+                      "isSecured": true
                     }
                 Secured and authorized :
                   summary: Secured and authorized
@@ -265,6 +278,18 @@ paths:
                     status: 400
                     title: Invalid Parameter
                     detail: Required parameter {0} is invalid. 
+        "422":
+          description: Unprocessable Entity
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"  
+              examples:             
+                Validation failed:
+                  value:
+                    status: 422
+                    title: OTP validation failed
+                    detail: The supplied OTP could not be validated
         "401":
           description: Unauthorized
           content:
@@ -295,8 +320,12 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-              example:
+              examples:
-                error: An unknown error has occurred
+                Internal Server Error:
+                  value:
+                    status: 500
+                    title: Internal Server Error
+                    detail: An unknown error has occurred
 components:
   securitySchemes:
     oAuthSample:  
@@ -304,12 +333,10 @@ components:
       description: This API uses OAuth 2 with the clientCredentials flow. [More info](https://api.example.com/docs/auth)
       flows:
         clientCredentials:   # <---- OAuth flow( clientCredentials)
-          tokenUrl: https://identity.{{env}}.api.htm.nl/oauth2/token
+          tokenUrl: https://identity.{env}.api.htm.nl/oauth2/token
           scopes:
-            profile
+            profile: "Access user profile"
   schemas:
-    unavailable:
-      type: object
     ErrorResponse:
       description: Default response when an invalid request has been sent
       type: object
@@ -330,10 +357,10 @@ components:
       description: Body for when the a new token entry is created
       type: object
       required:
-        - xTAT
+        - xTat
         - otpKey
       properties:
-        xTAT:
+        xTat:
           type : string
           description: >- 
             Unique identifier for the GBO transit account
@@ -351,12 +378,12 @@ components:
           type: boolean
           description: >-
             Is the OVpas secured according to the GBO
-          example: False
+          example: false
         isAuthorized:
           type: boolean
           description: >-
             Does HTM have the authorization to access the secured the data of the OVpas
-          example: False
+          example: false
     ValidateTokenBody:
       description: Body for when the a token entry is validated
       type: object
@@ -367,4 +394,6 @@ components:
           type : string
           description: >- 
             OTP to be used to secure the token and retrieve the JWT at GBO          
-          example: 1234567
+          minLength: 6
+          maxLength: 6
+          example: 123456