openapi: 3.0.1
info:
  title: Integraion 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.
  version: "1.0"
servers:
  - url: https://services.acc.api.htm.nl/abt/containertokens/1.0
tags:
  - name: tokens
paths:
  /tokens:
    parameters: 
    post:
      tags:
        - tokens
      summary: Create a new token entry in the vault
      description: Create a new token entry in the vault, if the customerProfileId has been supplied create in the customerToken DB otherwise in the AnonymousToken DB
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTokenBody"
            examples:
              token:
                value:
                  {
                    "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:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Missing Parameters:
                  value:
                    status: 400
                    title: Missing Mandatory Parameter
                    detail: Required parameter {0} is missing.
                Invalid Parameters:
                  value:
                    status: 400
                    title: Invalid Parameter
                    detail: Required parameter {0} is invalid.
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Unauthorized:
                  value:
                    status: 401
                    title: Unauthorized
                    detail: Invalid Access Token
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                TAT not found:
                  value:
                    status: 404
                    title: Not Found
                    detail: TAT Account Not Found
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: An unknown error has occurred
  /tokens/{xtat}/status:
    parameters: 
    - 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
    - name: customerProfileId
      in: query
      schema:
        type: integer
        example: 323
      required: false
      description: The id of the customer Profile for which the request is being done, if customer has identified themselves
    get:
      tags:
        - tokens
      summary: Request the security and authorization status of an OV pas token
      description: Request the security and authorization status of an OV pas token, if the customerProfileId has been supplied look in the customerToken DB otherwise check the AnonymousToken DB.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
               $ref: "#/components/schemas/TokenStatusResponse"
            examples:
                Not secured, not authorized :
                  summary: Not secured, not authorized
                  value:
                    {
                      "isAuthorized": false,
                      "isSecured": false
                    }
              Secured, not authorized :
                  summary: Secured, not authorized
                  value:
                    {
                      "isAuthorized": true,
                      "isSecured": false
                    }
              Secured and authorized :
                  summary: Secured and authorized
                  value:
                    {
                      "isAuthorized": true,
                      "isSecured": true
                    }
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Missing Parameters:
                  value:
                    status: 400
                    title: Missing Mandatory Parameter
                    detail: Required parameter {0} is missing.
                Invalid Parameters:
                  value:
                    status: 400
                    title: Invalid Parameter
                    detail: Required parameter {0} is invalid.
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Unauthorized:
                  value:
                    status: 401
                    title: Unauthorized
                    detail: Invalid Access Token
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                TAT not found:
                  value:
                    status: 404
                    title: Not Found
                    detail: TAT Account Not Found
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: An unknown error has occurred
  /tokens/{xtat}/validate:
    parameters: 
    - 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
    - name: customerProfileId
      in: query
      schema:
        type: integer
        example: 323
      required: false
      description: The id of the customer Profile for which the request is being done, if customer has identified themselves
    patch:
      tags:
        - tokens
      summary: Validate the supplied OTP and secure and/or authorize the token
      description: Validate the supplied OTP and secure and/or authorize the token if the customerProfileId has been supplied look in the customerToken DB otherwise check the AnonymousToken DB.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidateTokenBody"
            examples:
              token:
                value:
                  {
                    "otp": "1234564"
                  }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
               $ref: "#/components/schemas/TokenStatusResponse"
              examples:
                Not secured, not authorized :
                  summary: Not secured, not authorized
                  value:
                    {
                      "isAuthorized": false,
                      "isSecured": false
                    }
              Secured, not authorized :
                  summary: Secured, not authorized
                  value:
                    {
                      "isAuthorized": true,
                      "isSecured": false
                    }
              Secured and authorized :
                  summary: Secured and authorized
                  value:
                    {
                      "isAuthorized": true,
                      "isSecured": true
                    }
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Missing Parameters:
                  value:
                    status: 400
                    title: Missing Mandatory Parameter
                    detail: Required parameter {0} is missing.
                Invalid Parameters:
                  value:
                    status: 400
                    title: Invalid Parameter
                    detail: Required parameter {0} is invalid.
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Unauthorized:
                  value:
                    status: 401
                    title: Unauthorized
                    detail: Invalid Access Token
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                TAT not found:
                  value:
                    status: 404
                    title: Not Found
                    detail: TAT Account Not Found
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: An unknown error has occurred
components:
  schemas:
    unavailable:
      type: object
    ErrorResponse:
      description: Default response when an invalid request has been sent
      type: object
      properties:
        status:
          type: integer
          description: >-
            A status IS An integer that represents the HTTP status code of the
            response.
          example: 400
        title:
          type: string
          description: A title IS A string that provides a brief summary of the error.
        detail:
          type: string
          description: A detail IS A string that provides more details about the error.
    CreateTokenBody:
      description: Body for when the a new token entry is created
      type: object
      required:
        - xTAT
        - otpKey
      properties:
        xTAT:
          type : string
          description: >- 
            Unique identifier for the GBO transit account
          example: 03071794-482a-4168-b60f-84669a9e6a76
        otpKey:
          type : string
          description: >- 
            Key used to validate the OTP at GBO
          example: 123456789123456789123456789abcde
    TokenStatusResponse:
      description: Response for when the status of a token is requested
      type: object
      properties:
        isSecured:
          type: boolean
          description: >-
            Is the OVpas secured according to the GBO
          example: False
        isAuthorized:
          type: boolean
          description: >-
            Does HTM have the authorization to access the secured the data of the OVpas
          example: False
    ValidateTokenBody:
      description: Body for when the a token entry is validated
      type: object
      required:
        - otp
      properties:
        otp:
          type : string
          description: >- 
            OTP to be used to secure the token and retrieve the JWT at GBO
          example: 1234567