# Change Control
# ===============
# Version    Date        Author             Change Description
# 1.0.0      26/08/2024  Viswanathan K      Initial version
# 1.0.0      07/11/2024  Viswanathan K      Updated security schemes
# 
#

openapi: 3.0.0
info: 
  title: Authentication
  version: 1.0.0
  description: "Authentication API generates access token that is required to authorize API requests by consumers"
   
  contact: 
    name: Colt Reseller Support Voice
    email: ResellerSupport.Voice@colt.net
    
servers:
  - url: https://uat.apis.colt.net/authentication
    description: Production server
  - url: https://rfs.apis.colt.net/authentication
    description: Sandbox server
security:
  - basicAuth: []

tags: 
  - name: OAuth Access Token
 
paths:

  /v1/oauth/token:
    post:
      operationId: getAccessToken
      tags: 
        - OAuth Access Token
      description: "The API generates access token that is required to authorize API call by a registered App. The access token has limited validity period and the expiry time is returned in the response."    
      parameters:
      - name: x-tracking-id
        in: "header"
        required: true
        description: "Unique identifier for the request"        
        schema:
          $ref: '#/components/schemas/trackingIdTypeV1'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/accessTokenRequestV1'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accessTokenResponseV1'
          headers:
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
            content-type: 
              schema:
                type: string
                enum:
                  - application/json                
        "400":
          description: Bad Request
          headers:          
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "401":
          description: Unauthorized
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "403":
          description: Forbidden
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "404":
          description: Not Found
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "405":
          description: Method Not allowed
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "406":
          description: Not Acceptable
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                
        "413":
          description: Payload Too Large
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                 
        "415":
          description: Unsupported Media Type
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1' 
        "429":
          description: Too Many Requests
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                 
        "500":
          description: Internal Server Error
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'  
        "503":
          description: Service Unavailable
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'  
        "504":
          description: Gateway Timeout
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'             
  
  
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    
  schemas:
    trackingIdTypeV1: 
      type: string
      description: "Unique identifier for the request"
      example: abcd456e-d45645-dfaafda-1232345667dd
      pattern: "^[a-zA-Z0-9_.~:@-]{1,255}$"
      maxLength: 255

    exceptionSystemTypeV1:
      type: string
      enum:
        - 'APIGW'
        - 'IDP'

    errorTypeV1:
      description: 'Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)'
      type: object
      required:
        - code
        - reason
      properties:
        code:
          type: string
          description: 'Application relevant detail, defined in the API or a common list.'
          example: ERR01
        reason:
          type: string
          description: Explanation of the reason for the error which can be shown to a client user.
        message:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client user.

    accessTokenRequestV1:
     type: object
     required:
       - grant_type
     properties:
      grant_type:
        type: string
        description: "The authentication scenario to get an access token from the authorization server. Only 'client_credentials' is supported."
        enum: 
          - client_credentials
          
    accessTokenResponseV1:
     type: object
     required:
       - access_token
       - token_type
       - expires_in     
     properties:
        access_token:
          type: string
          description: The access token issued by the OAuth server.
          example: eyJraWQiOiIxMTM4NzQwNTI2NDMyMDE0NjcyODI1MTY0NDE4NDg3NDY3NjUzOCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJodHRwczovL3NpdGF1dGguY29sdC5uZXQ6ODQ0My9uaWRwL29hdXRoL25hbSIsImp0aSI6IjRkMDZhMjExLTc3OTAtNGJlNi05NTBiLTk3MjdlODhmZjBjOSIsImF1ZCI6IjI3YjQ1NDA1LTFjZGUtNDA3Ni1iZGUwLThmMzM3MjUwOWNkYSIsImV4cCI6MTY3OTkxNTU3MywiaWF0IjoxNjc5OTEzNzczLCJuYmYiOjE2Nzk5MTM3NDMsInN1YiI6IjI3YjQ1NDA1LTFjZGUtNDA3Ni1iZGUwLThmMzM3MjUwOWNkYSIsIl9wdnQiOiJ3Q0FkU2JvYkY4d1pNc2xETU4xV1NkUDNneGt6K2c2RHJhTWJENkx5bUE1ZmpzZDVIMWV5bk5YdXQrSDdVbi9uVERyYXN6bzVUYjBadTNmcnYwZThtZ01qT0xnbUg0bVRhZXVqNXdvcW9HdFhlcUNhT1R4L0JyN2VIRTZoOVhOMTA3UGRSREVVNjRId1FtNlE2SXl3WmVzRnJqV1VETU8rTEg3eUxacEQ5T3FTUDZSb2JadDBBQ09MV1k5L0VoU2JHMnR5aXBzenY3ZDhjdlA2NC9neFBJdXY1eUN0eXVsQ2VGS0RNVVY2MHljPS43Iiwic2NvcGUiOltdfQ.JKkOQ7UPHogJG_QdK7dRJTGir090fp2CFT1_2bx01zQ9WVSraIfVeVY3jytkm0b_6J0r8Sc8Td_THckQ2zJrMXwna-140b1wPNuQynXGzDve2ypg9dXH6Wj_wlegP5lCLSxQkKF_z-RZxeNUDt85fWzINtcCEZFAcEnpR2DAxjvSvu3UXhNColRsaSfs3DH39DCPjxX0ZmnFSrZ9hKu621oKNk9yBDeH_GYHVOAgTktXcU95oNhpQOgOEko56JosumXBknxjy6BoGLpmPnG4SslAsStrLeLgK5PBbUwC6IpGQqKFvjyxLWnOOmLA_F3C1PxqESQeHwzex82VoZawqQ
        token_type:
          type: string
          description: The type of the token issued.
          example: Bearer
        expires_in:
          type: integer
          description: Duration for which token is active in seconds.
          example: 3600          
          