openapi: 3.0.0
info:
  title: Embed Token API
  description: API for creating and managing embedded tokens for secure frontend integration
  version: 0.0.2
  contact:
    name: Swift Developer Portal
    email: developer-support@swift.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: http://sandbox.swift.com/frontend/v1
    description: Sandbox environment

paths:
  /embed-token:
    post:
      summary: Create a new embed token
      description: Create a new embed token
      operationId: createEmbedToken
      requestBody:
        description: Embed Token object to be created
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbedTokenInput'
            example: 
                {
                  "properties": [
                      {
                          "name": "templateId",
                          "value": "2"
                      },
                      {
                          "name": "showHeader",
                          "value": "true"
                      },
                      {
                          "name": "colour",
                          "value": "#197367"
                      } ,
                      {
                          "name": "alignment",
                          "value": "VERTICAL"
                      } ,
                      {
                          "name": "uetrs",
                          "value": "00f4be35-76f2-45c8-b4b3-565bbac5e86b"
                      }    
                  ]
                }
      responses:
        '200':
          description: Embed Token object successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbedToken'
              example: 
                {
                "tokenType": "Embed",
                "expiresIn": "29",
                "embedURL": "https://prototypes.swift.com/tracker-fe-gui/track?uetr=00f4be35-76f2-45c 8-b4b3-565bbac5e86b&token=dx1LmWfw9YTGasMgIs9BghIbAp1L",
                "embedToken": "dx1LmWfw9YTGasMgIs9BghIbAp1L",
                "tokenId": "tok_f9e4c09d"
                }
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              examples:
                invalidInput:
                  summary: Invalid request parameter
                  value:
                    severity: Fatal
                    code: SwAP504
                    text: "Request validation failed with reason: ..."
        '401':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              examples:
                Unauthorized:
                  summary: Unauthorized
                  value:
                    severity: Fatal
                    code: SwAP502
                    text: Invalid OAuth access token
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"
              examples:
                Forbidden:
                  summary: Forbidden
                  value:
                    severity: Fatal
                    code: SwAP503
                    text: App is not subscribed to the product being requested.
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"
              examples:
                tooManyRequests:
                  summary: Too Many Requests
                  value:
                    severity: Transient
                    code: SwAP507
                    text: Request cannot be processed at this time. Please try again
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"
              examples:
                gatewayTimeout:
                  summary: Service Unavailable
                  value:
                    severity: Transient
                    code: SwAP590
                    text: Service is temporarily unavailable.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"
              examples:
                gatewayTimeout:
                  summary: Gateway Timeout error
                  value:
                    severity: Transient
                    code: SwAP591
                    text: Request cannot be processed at this time. Please try again
      security:
        - bearerAuth: []

components:
  schemas:
    EmbedToken:
      type: object
      required:
        - embedToken
        - embedURL
        - expiresIn
        - tokenType
        - tokenId
      properties:
        embedToken:
          type: string
          description: The encoded embed token for frontend use
        embedURL:
          type: string
          description: The HTML converter URL
        tokenId:
          type: string
          description: Unique identifier for the embed token
        expiresIn:
          type: string
          description: Token expiration in miliseconds
        tokenType:
          type: string
          description: Type of token


    EmbedTokenInput:
      type: object
      required:
        - properties
      properties:
        properties:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EmbedTokenProperty'

    ErrorMessage:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error message
        details:
          type: object
          nullable: true
          description: Additional error details
    EmbedTokenProperty:
      type: object
      required:
        - name
        - value
      properties: 
        name:
          type: string
          description: name of the property
        value:
          description: value of the property
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token authentication